Parameter Builder Library: Server-Side Onboarding Guide

// Update the dependencies in your package.json. Run npm install. 
"dependencies": {
      "capi-param-builder-nodejs": {version}
}

// Example below is in Gradle Groovy. Edit your build.gradle:
dependencies {
    implementation 'com.facebook.capi.sdk:capi-param-builder:{current_version}'
}

// Install the library using pip. Run the following command lines.
pip install capi_param_builder_python
        
// Verify the installation by ```pip list```

gem install capi_param_builder_ruby

// This PHP example uses drupal/eu_cookie_compliance as third-party cookie consent and may be replaced with whatever the customer uses. For more details, please review the full example at https://www.google.com/url?q=https://capi-automation.s3.us-east-2.amazonaws.com/public/php/example/drupal.zip&sa=D&source=docs&ust=1747687304480502&usg=AOvVaw0z75y_J_zIyHprgIfHq0lt    
/**
   * Fetches cookies from the HTTP request.
   */
  public function onKernelRequest(RequestEvent $event) {
    $request = $event->getRequest();
    $http_host = $request->getHost();
    $get_params = $request->query->all();
    $referer = $request->headers->get('referer');
    $x_forwarded_for = $request->headers->get('X-Forwarded-For');
    $remote_addr = $request->getClientIp();

    // Get COOKIE values equivalent.
    $cookies = $request->cookies->all();
    // if EU Cookie Compliance module is being used
    if (isset($cookies['cookie-agreed'])) {
      // Get the value of the 'cookie-agreed' cookie.
      $this->cookieAgreed =
        $cookies['cookie-agreed'] == self::COOKIE_AGREED_VALUE;
    }
    if($this->cookieAgreed){
        $this->param_builder->processRequest(
          $http_host,
          $get_params,
          $cookies,
	    $referer ?? null,
    $x_forwarded_for ?? null,
    $remote_addr ?? null
      );
    }
  }
  /**
   * Sets a cookie in the HTTP response.
   */
  public function onKernelResponse(ResponseEvent $event) {
    if($this->cookieAgreed){
      // Add the cookie to the response.
      $response = $event->getResponse();
      foreach ($this->param_builder->getCookiesToSet() as $cookie) {
        $response->headers->setCookie(new Cookie(
          $cookie->name,
          $cookie->value,
          time() + $cookie->max_age,
          '/',
          $cookie->domain
        ));       
      }
    }
  }

const builder = new ParamBuilder([‘example.com’, ‘....’]);


 if (!cookieString) {
   return null;
 }
 const cookies = {};
 const items = cookieString.split('; ');
 for (const item of items) {
     const [name, value] = item.split('=');
     cookies[name] = value;
 }


 const cookiesToSet = builder.processRequest(
   req.headers.host, // host
   params, // query params
   cookies, // current cookie
   req.headers.referer ?? null, // optional, help enhance the accurancy
   req.headers['x-forwarded-for'] ?? null,
   req.socket.remoteAddress ?? null
 );


 const cookies = [];
 for (const cookie of cookiesToSet) {
   cookies.push(cookie.name + '=' + cookie.value + '; Max-Age=' + cookie.maxAge + '; Domain=' + cookie.domain + '; Path=/');
 }
 res.setHeader('Set-Cookie', cookies);

   
}

ParamBuilder paramBuilder = new ParamBuilder(Arrays.asList("example.com", '....'));
   Map<String, String> cookieMap = getCookiesToMap(request.getCookies());
   List<CookieSetting> updatedCookieList =
       paramBuilder.processRequest(
           request.getHeader("host"), request.getParameterMap(), cookieMap);
   for (CookieSetting updatedCookie : updatedCookieList) {
     Cookie cookie = new Cookie(updatedCookie.getName(), updatedCookie.getValue());
     cookie.setMaxAge(updatedCookie.getMaxAge());
     cookie.setDomain(updatedCookie.getDomain());
     response.addCookie(cookie);
   }

from capi_param_builder import ParamBuilder


# Main function declaration
# We support DefaultEtldPlusOneResolver() from demo, please
fbcBuilder = ParamBuilder(["example.com", "...."])
# host: str, queries: dict[str, str], cookies: dict[str, str]
updated_cookies = fbcBuilder.process_request(
     domain_only, query_params, cookie_dict
)


# Set cookie
for cookie in updated_cookies:
           self.send_header(
               "Set-Cookie",
  f"{cookie.name}={cookie.value};Max-Age={cookie.max_age};path=/;domain={cookie.domain}",
           )

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

// Get builder 
const builder = new ParamBuilder(["example.com", "your-domain.com"]);

// Get cookies from request
const requestCookies = parseCookie(req.headers.cookie);
builder.processRequest(
    req.headers.host, // host
    params, // query params
    requestCookies, // current cookie
    req.headers.referer ?? null, // optional, help enhance the accurancy
    req.headers['x-forwarded-for'] ?? null,
    req.socket.remoteAddress ?? null
  );

const fbc = builder.getCookiesToSet().getFbc();
const fbq = builder.getCookiesToSet().getFbq();
const clientIpAddress = builder.getClientIpAddress();
const email = builder.getNormalizedAndHashedPII(' John_Smith@gmail.com    ','email');
const phone = builder.getNormalizedAndHashedPII('1(650)123-4567','phone');

// Pass the fbc, fbp, clientIpAddress, email and phone number to the Conversions API

ParamBuilder paramBuilder = new ParamBuilder(Arrays.asList("example.com", "your-domain.com"));
   Map<String, String> cookieMap = getCookiesToMap(request.getCookies());
   List<CookieSetting> updatedCookieList =
        paramBuilder.processRequest(
            request.getHeader("host"), request.getParameterMap(), cookieMap);

String fbc = paramBuilder.getFbc(cookieMap);
String fbp = paramBuilder.getFbp(cookieMap);
        
// Pass the fbc and fbp to the Conversions API

fbcBuilder = ParamBuilder(["example.com", "your-domain.com"])
       # host: str, queries: dict[str, str], cookies: dict[str, str]
       updated_cookies = fbcBuilder.process_request(
           domain_only, query_params, cookie_dict
       )
       # after process_request got called, you could call get_fbc() and get_fbp() to get the actual value for fbc and fbp
       fbc = fbcBuilder.get_fbc()


       fbp = fbcBuilder.get_fbp()
        
# Pass the fbc and fbp to the Conversions API

builder = ParamBuilder.new(["localhost", "example.com"]) 
cookies_to_be_updated = builder.process_request(
        host, # current host name
        query_params, # query params as hash type
        cookie_dict, # current cookies as hash type
        referral_link) # optional current referer
# recommended to save cookies_to_be_updated to your cookies.
 
# after process_request got called, you could use get_fbc and get_fbp to get the actual value
fbc = builder.get_fbc()
fbp = builder.get_fbp()
        
# Pass the fbc and fbp to the Conversions API

/*
//Currently we provide 3 options; you may also implement your own resolver.

1. [Recommended] Resolve etld+1 by default
     const etldPlus1Resolver = new DefaultETLDPlus1Resolver();
2. Resolve by half manual input
     const etldPlus1Resolver = new DefaultETLDPlus1Resolver('www.example.com'); // => 'example.com';
3. Manual identify etld+1 (mostly for localhost test).
     const etldPlus1Resolver = new DummyLocalHostTestResolver('localhost');
4. Implement a new resolver by yourself. Example below:

*/
    
class SimpleETLDPlus1Resolver {
   resolveETLDPlus1(domain) {
	if (isSubdomain(domain, "example.com")) {
	return "example.com";
}
      // throw exception or fallback to other functions
   }

// We provide DefaultETLDPlusOneResolver, which uses Guava InternetDomainName to resolve ETLD+1. If you prefer to do it yourself, follow the example below:

public class SimpleETLDPlusOneresolver implements ETLDPlusOneResolver {
	@Override
	public String resolve(String domain) {
               if (isSubdomain(domain, "example.com")) {
	       return "example.com"
               }
               // throw exception or fallback to other function
        }
}

# We provide a default_etld_plus_one_resolver.py within the example file. Feel free to implement your own solutions. 
        
from capi_param_builder import EtldPlusOneResolver

        
class DefaultEtldPlusOneResolver(EtldPlusOneResolver):
   """
   Default implementation of EtldPlusOneResolver
   """


   def resolve(self, host_name: str) -> Optional[str]:
        # Start your implementation to get etld+1 from host_name
        etld_plus_one = host_name
        # Return the resolved etld+1
        return etld_plus_one

# Please check the Ruby example from the README demo for the full context.
        
require 'capi_param_builder/etld_plus_one_resolver'

class DefaultEtldPlusOneResolver < EtldPlusOneResolver
   def resolve(host_name)
        # Your implementation
        return host_name
   
   end

end