krolewskie-miody.pl/wp-content/plugins/facebook-for-woocommerce/vendor/facebook/capi-param-builder-php/ruby

Conversions API parameter builder for Ruby

Introduction

The Conversions API param builder is a light weighted SDK to help improve the Conversions API params' retrieval and quality.

Server-Side Parameter Builder Onboarding Guide

Quick Start

1. Check the latest version in CHANGELOG.

2. Install the library.

gem install capi_param_builder_ruby

3. Verify by run

gem list | grep capi_param_builder_ruby

Verify the SDK name and version.

Demo

1. Checkout demo application ./example

2. Install the capi_param_builder library, from above #Quick Start. Also install optional 3rd party library(sinatra, public_suffix) to run the demo.

2.1 sinatra. Install by running gem install sinatra. An easy web framwork.

2.2 (optional) public_suffix. Install by running gem install public_suffix. It will help resolve etld+1, if you'd prefer to use this option to get your etld+1 domain. It's used under./resolver/default_etld_plus_one_resolver.rb as one example to use etld+1 resolver. For usage, please check in #Usage section below.

3. Run local demo server. Once you have capi_param_builder, sinatra library installed. Run the demo application.

cd ./example
ruby app.rb

4. Verification.

   4.1 Visit http://localhost:4567/. You'll see the demo page with fbc and fbp value printed on main page. Open dev inspector to check the cookies, same value should be in _fbc and _fbp. fbc might be null if this is your first time visiting.

   4.2 Visit http://localhost:4567/?fbclid=this_is_my_test. You'll see the _fbc and fbc value changed. The new value should contain the string this_is_my_test. The _fbp value should be the same as 4.1.

   4.3 Visit http://localhost:4567 again. You'll see the _fbc and _fbp stays the same as 4.1 and 4.2.

API usage

This section explains how to use the SDK. And provide suggestions on the API usage.

1. Install the capi_param_builder library, from above #Quick Start.
2. Import the class as require 'capi_param_builder'
3. Construct your ParamBuilder. We provide 3 options.

[Recommended] Option 1: Provide a list of etld+1. We'll use the etld+1 to match your current hostname, then provide recommended update cookies' domain.

builder = ParamBuilder.new(["localhost", "example.com"])

Option 2: Provide an ETLD+1 resolver. Implement a customized ETLD+1 resolver to provide the preferred etld+1 to save the cookies to.

# example implementation DefaultEtldPlusOneResolver from example/resolver. Feel free to provide your owne resolver.

builder = ParamBuilder.new(DefaultEtldPlusOneResolver.new())

Option 3: [Not recommended] empty input. We'll return one level down from your input host. May miss some accuracy.

builder = ParamBuilder.new()

4. Call process_request function to process fbc and fbp

cookies_to_be_updated = builder.process_request(
   domain, # str: current host
   name query_params, #dict[str, List[str]]: query params as hash type
   cookie_dict,#dict[str, str]: current cookies as hash type
   referral_link) #Optional[str]: optional current referer

5. [Recommended] Save cookies_to_be_updated as first-party cookies. This helps keep consistent fbc and fbp among your events. Based on your webserver framework, the save cookie API may vary. Feel free to choose the best fit for your use case. Below uses the example from demo application.

Option 1: Save the cookies_to_be_updated cookies from process_request to your response.

# Get the recoomended saved cookie from step 4 above

cookies_to_be_updated = builder.process_request(...)

for cookie in cookies_to_be_updated do response.set_cookie(
    cookie.name,
    value: cookie.value,
    domain: cookie.domain, path: "/",
    # for sinatra the expires is an absolute ts
    # Check your web framework to have the correct expires.
    expires: Time.now + cookie.max_age)
end

Option 2: Save the recommended cookies from get_cookies_to_set to your response.

# Get the recoomended saved cookie from step 4 above

builder.process_request(...)

# `cookies_to_be_updated` from get_cookies_to_set()

for cookie in builder.get_cookies_to_set() do
   response.set_cookie(
      cookie.name,
      value: cookie.value,
      domain: cookie.domain,
      path: "/",
      # for sinatra the expire time, is an absolute ts
      # Check your web framework to have the correct expires.
      expires: Time.now + cookie.max_age)
end

6. get correct fbc and fbp.

fbc = builder.get_fbc()

fbp = builder.get_fbp()

7. Send fbc and fbp back with the Conversions API.

data=[
   'event_name: '...',
   'event_tme': <your_time>,
   'user_data': {
      'fbc': fbc, // The value provided in step 5
      'fbp': fbp, // The value provided in step 5 ...
   }
...
]

License

Conversions API parameter builder for Ruby is licensed under the LICENSE file in the root directory of this source tree.