Adform integration

Note: Completing this procedure requires some knowledge on sending API requests using cURL, Postman, or similar tools.

You can use the Dynamic Content and Automation modules to match customers and send segments of customers to Adform.

Alternative way for Cookie Matching

The basic way of matching Synerise and Adform identifiers is to use Cookie Matching method - which is described in this guide. However, there are some solutions during the developement that enable ID matching by using actions from the server. To obtain more details about it, please contact us at synerise.com/support.

Process overview


To create the integration that sends a segmentation to Adform, follow the steps listed below:

  1. ID Cookie matching on Web
  2. ID Cookie matching on Mobile
  3. Setting Adform id as attribute
  4. Share segmentation

In this part of the process, you match the Adform ID with a Synerise client.

In the browser, Adform issues an ID in a cookie named uid from the adform.co.uk domain. This cookie is unique within your browser and resets itself in the following cases:

  1. Clearing cookies in the browser
  2. Expiration of a cookie (60 days)
  3. Mechanisms on the website that enforce the right of users to be forgotten (clearing cookies)
Important: This value is not returned by calling document.cookie.

Since one customer can use multiple devices, it is necessary to store multiple Adform IDs per a customer in Synerise. The Adform ID is stored in the adFormID attribute, which will take values separated by | (the unique Adform ID collected from the browser or application), for example:

 "adFormID": "2122903280729231000|2122903280729231001", 

You can prepare a dynamic content with the code that matches the Adform ID with the UUID from Synerise by adding a value to the adFormID attribute. It is important that the value is added, not overwritten.

Retrieve Adform ID from source

WEB: Pixel initiated via Dynamic Content
Below the the dynamic content code:

(function () {
function loadScript(src, callback) {
    let script = document.createElement('script');
    script.src = src;
    script.onload = function () {
        return callback(window.Adform);
    };
    document.head.append(script);
}
function checkAdform(instance) {
    if (!instance || !instance._uid) {
        console.log('no uid')
    } else {
        var oldUid = "{% if 'adFormID' in customer | string %}{{ customer['adFormID'] }}{% else %}brak{% endif %}";
        if (oldUid === 'brak' || oldUid.indexOf(instance._uid) === -1) {
            SR.event.trackCustomEvent('adformid.save', {
                newId: instance._uid.toString(),
            });
            console.log('adform uid sent -> ' + instance._uid);
        }
    }
}
loadScript('https://track.adform.net/serving/cookie/?adfaction=getjs;adfcookname=uid', checkAdform)
})();

Such a pixel is initialized on all pages for all users (both recognized and unrecognized). It retrieves the current value of the adFormID attribute and sends an event only if the Adform ID from the browser is no longer among those assigned to the attribute.

The dynamic content configuration of the matching pixel
The dynamic content configuration of the matching pixel


The cookie matching is based on the Adveritising ID, which is a fixed ID for a given device issued by Google.

Currently, Advertising ID is not collected through our SDK. You must implement such tracking in the application. You can do this by sending a custom event.

Mobile events implementation

{
  "label": "custom.event",
  "action": "adformid.save,
  "client": {
  "uuid": "xxx", // uuid from mobile app
  },
  "params": {
    "newId": "ADVERTISEMENT_ID"
    "source": "MOBILE_APP"                                   
    }
}
Important: Event should be sent once per user

The custom event available on the activity list on the customer’s profile:

The output of custom event sent from mobile
The output of custom event sent from mobile

Saving Adform ID as an attribute


Create a workflow that is triggered by the adformid.save event and adds the ID it contains to the current value of the client attribute.

The configuration of the workflow
The configuration of the workflow
  1. In Synerise, go to Automation > Workflows > New workflow.

  2. As the first node, select Client Event. In the node configuration:

    1. Select the adformid.save event.
    2. As the parameter of the event, select newId.
    3. As the logic operator select Regular expression.
    4. As the formula of the regular expression, enter ., which means that all values are considered (except for null).
    5. Confirm by clicking Apply.
    The configuration of the Client Event trigger
    The configuration of the Client Event trigger
  3. After the Client Event, add the Update Client node. In the node configuration:

    1. From the dropdown list, select adFormID.
    2. From the dropdown list, select Change.
    3. In the field enter the following formula:
      {% set currentValue = customer['adFormID'] %}{% set newVal = event.params.newId | string %}{% set currentValues = currentValue | split('|') %}{% do currentValues.append(newVal) %}{% set finalValues = [] %}{% if currentValue|length > 255 %}{% for x in currentValues %}{% if loop. index0 > 0 %}{% do finalValues.append(x) %}{% endif %}{% endfor %}{% else %}{% if newVal in currentValue %}{% catalog.kill(it) %}{% else %}{% set finalValues = currentValues %}{% endif %}{% endif %}{{ finalValues | join('|') }}
          

    The insert above includes the following solution: Before adding an attribute, the workflow checks again whether the new ID is not already among the stored ones and checks whether the attribute will not exceed 255 characters after adding the new ID. If it does, the oldest assigned ID is deleted.

    The configuration of the Update Client node
    The configuration of the Update Client node
  4. Finish the workflow with the End node.
    Result:

    Updated attribute in the customer's profile
    Updated attribute in the customer's profile

Share segmentation


To send the segment of customers from Synerise to Adform, you must prepare the group of customers in Synerise. The next step is to prepare a workflow, which for a specific audience will issue a CSV file according to Adform specifications.

adform output file
The configuration of the file output
  1. In Synerise, go to Automation > Workflows > New workflow.

  2. As the first node add the Audience node. In the node configuration, define the filters to include customers.

    Tip: You can read more about creating segmentations.

  3. As the second node, add the Outgoing Integration node.
    Explanation: The workflow sends webhook to the morph diagram with a single file record. Morph adds the received data to the file. With the schedule set, morph dumps the files to Amazon Bucket. Adform retrieves the files from Amazon Bucket (periodically, depending on the customer). At this point, it is important to obtain Amazon Bucket credentials and provide in the Outgoing webhook node.

    Note: At this point you define the file output from Synerise Automation module.

    Adform file specification

    File Pattern:

    18331041030194574295 CCC000GL,CCC000SL
    22721909998410229190 CCC000GL,CCC000LS
    33973889829511705327 CCC000GL

    Legend:

    • file columns explanation: adformID and ownerID
    • adformID - ID of the cookie in Adform
    • ownerID - ID of the segment(s) in the adform, can be several decimal places The file must be sent in CSV format.
    Updated AdformID attribute
    Updated AdformID attribute

    Example configuration of Outgoing webhook

    adform id client node
    The configuration of the update client node
    Important: To obtain the endpoint, contact us at synerise.com/support

    Example request body:

        {% set ids = customer[‘adFormID’]|split(‘|') %}
    [
    {% for x in ids %}
    {
    “user”: “{{ x }}	1234567"
    }
    {% if loop.index != ids | count %},{% endif %}
    {% endfor %}
    ]

Remember:

  1. The Adform IDs in a file may repeat.
  2. The given segments will be added to the user in the Adform, not overwritten. This means that it is safe to specify the same user several times in one file and assign different segment IDs to the user (resulting in all segments being assigned to him collectively).
Note: If you need further assistance in automation configuration please contact us at synerise.com/support
😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.