Account Linking

We use the Facebook Pixel to enable publishers to connect a subscriber from their own systems to an authenticated Facebook user.

This connection is made by capturing key points in a subscriber's journey using specific signed Pixel events that include a subscription_id provided by publishers. This connection can only be created from a browser context, so Pixel events must be sent from the client-side where possible using the <img> tag. After a user is identified as a subscriber via one of the Pixel events they will be presented a screen where they can consent to the accounts being linked. Users can also opt to unlink their accounts at any later point.

Because these events are functional Pixel events, they are also available in Facebook Analytics to provide key metrics relevant to your Instant Articles Subscriptions.

For important events that occur outside of the frontend of your article website, publishers can use the Subscriptions Syncing API to send deferred events, such as cancellations via telephone or email.

The tables below list the Pixel events and parameters used for Account Linking.

Event name Description Required Custom Properties

Subscribe

User has successfully paid for a subscription package.

  • subscription_id
  • offer_code
  • value
  • currency

LogIntoAccount

User logs into their account on a publisher's website, either with or without a subscription entitlement.

  • subscription_id
  • is_subscriber

Event Custom Properties

Parameter name Data type Description Example

subscription_id

string (alphanumeric only)

User identifier, account ID or similar that uniquely maps to a user on a publisher's systems.

abcd123456

offer_code

string

Publisher specified code that indicates which Subscription offer a user has selected

monthly_combo

value

integer or float

The value of the subscription purchased

2.99

currency

string

The currency for the value specified

USD

is_subscriber

boolean (lowercase)

Whether or not the provided subscription_id is currently an active subscriber

true

expiry_time

string

A string in ISO8601 format representing the expiry time of the subscription. The default is -1, meaning the subscription will never automatically expire and you must manually expire it with the Subscription Syncing API. Expiry time must be over 1 month in the future.

2018-06-07T17:55:00+00:00

Signed Pixel Event

For added security and to prevent unauthorized access to locked content, we require events sent to Facebook for Instant Articles Subscriptions to be securely signed your Facebook App's App Secret. The App Secret should only be known to Facebook and the App owner, which ensures that no one else can create similar Pixel events.

Retrieving your App Secret

You can retrieve your App Secret in the settings of you App. Please make sure you use the App Secret from the App that you have linked in the initial setup.

Please ensure your App Secret is kept securely and not distributed.

Signed Events Requirements

The following query parameters must be included when sending an Account Linking pixel event:

Query Parameter Name Description

id

Your Pixel ID

ev

The Pixel event being sent (e.g. Subscribe)

cd[param_name]

The required custom properties for the pixel event you are sending (e.g. cd[value]=0.99&cd[currency]=USD&cd[subscription_id]=abcd)

eid

A unique identifier for the signed event you are providing, e.g. a random GUID/UUID

ts

The epoch timestamp when the event was created, in milliseconds - events must be sent as soon as possible, as events created more than 3 hours before the current time are rejected.

sig

Base64 encoded HMAC-SHA256 hash of the URL encoded query string (of all the other parameters above), signed using your App Secret. This signature is used to verify the authenticity of the received pixel event.

Sample Implementation (PHP)

      <?php
            
      function generate_signed_fb_event_tag($event_name, $event_data) {
          $pixel_id = '<YOUR_PIXEL_ID>';
          $app_secret = '<YOUR APP SECRET>';
          $payload = array(
              'id' => $pixel_id,
              'ev' => $event_name,
              'cd' => $event_data,
              'noscript' => 1
          );
          return buildBrowserTag($payload, $app_secret);
      }
      
      function buildBrowserTag(
          array $params,
          string $secret,
          string $base_url = 'https://www.facebook.com/tr'
        ) {
          $params['eid'] = bin2hex(random_bytes(16));
          $params['ts'] = time() * 1000;
          $query_str = encodeToQueryString($params);
          $signature =
            urlencode(base64_encode(hash_hmac('sha256', $query_str, $secret, true)));
          $uri = $base_url .'?'.($query_str.'&sig='.$signature);
          return "<img src='{$uri}' style='display: none;' />";
      }
          
      function encodeToQueryString(array $params) {
          $encoded_params = array();
          foreach ($params as $key => $value) {
            if (!is_array($value)) {
              $value = urlencode($value);
              $encoded_params[] = "{$key}={$value}";
            } else {
              $inner_params = array();
              foreach ($value as $inner_key => $inner_value) {
                $value_to_set = is_string($inner_value)
                  ? $inner_value
                  : json_encode($inner_value);
                $value_to_set = urlencode($value_to_set);
                $key_to_set = urlencode("[".$inner_key."]");
                $inner_params[] = "{$key}{$key_to_set}={$value_to_set}";
              }
              $encoded_params[] = implode('&', $inner_params);
            }
          }
          return implode('&', $encoded_params);
       }      

      ?>
      
      <?php 
      echo generate_signed_fb_event_tag(
          'Subscribe',
          array(
              "value" => 0.99,
              "currency" => "USD",
              "subscription_id" => "abcd"
          )    
        ); 
      ?>
    

Example result of the code execution

      
<img src='https://www.facebook.com/tr?id=421576054920537&ev=Subscribe&cd%5Bvalue%5D=0.99&cd%5Bcurrency%5D=USD&cd%5Bsubscription_id%5D=abcd&noscript=1&eid=57d3b0ca224085ca79b34ab1338ac8d7&ts=1537165733000&sig=BFql%2BGjxLxNx0s41DDqFerqn16ClEki9%2FsK4N0GI6Cc%3D' style='display: none;' />
    

Pixel URL Validator (Validate Your Pixel Signature)

To make sure that your event has been signed correctly, you can validate the fired Pixel event with Pixel URL Validator located in Publishing Tools -> Instant Articles -> Subscriptions -> Developer Tools. Simply copy a generated Pixel event URL (inside <img> src tag) and paste it inside Signed Pixel URL to validate. Make sure to start the URL with https://www.facebook.com/tr and use the right Pixel ID as provided in the Initial Setup.

Example after running a validation against a Pixel event, along with the result and explanation: