Overview

Criteo

This guide will walk you through how to setup your campaigns with Criteo using Branch Universal Ads and track ad conversions across every device, platform, and channel. Universal Ads provides everything you need for complete tracking, including rich data for the Criteo Engine to optimize against.

1. Complete Universal Ads Prerequisites

DEVELOPER MAY BE REQUIRED

The following Universal Ads prerequisite includes providing URI schemes and other components that may require a developer:

DEVELOPER REQUIRED

The following Universal Ads prerequisites involve app code changes:

2. Enable the Integration

  1. Visit the Ads page on the Branch dashboard.
  2. Select Partner Management from the sidebar.
  3. Search for your Universal Ads Partner.
  4. Select Criteo and hit Save & Enable.

3. Enable Postbacks

Basic postbacks will automatically be activated for events like Install and Purchase when you enable your ad partner.

You can then add additional postbacks, for example, if you wanted to add postbacks for custom events that are specific to your app like Account Created.

You can also edit postbacks if there's additional data you really need to pass along to your ad partner.

3a. Resetting Postbacks

There may be times when you need to reset a partner's settings; i.e. when a partner updates their postback templates or when perhaps you've made a mistake during partner setup. Resetting a partner's settings allows you to re-enable the partner integration with the correct information to accurately measure and attribute conversion.

Disables Ad Partner

Resetting partner settings will:

  • Disable the ad partner.
  • Clear out all of your saved credentials and postbacks that are already setup.
  • Return the ad partner to its basic configuration.

Updating Postbacks

  • Please do NOT reset Criteo Postbacks settings as it will override the previous postbacks.
  • Make sure to replace old versions of the event postbacks with new ones gradually one by one.

4. Criteo Link Options

4a. Catalog Deep Links

Recommended

Branch links function as Universal Links or App Links, as well as deferred deep links, meaning better conversions on all Criteo campaigns.

The same Branch link will do measurement as well as deep linking, so there's no need for additional "tracking-only" links. In fact, if you're using Branch links as your campaign links, you shouldn't use additional server to server tracking as well.

Criteo accepts a catalog with product details and links. We recommend replacing your web links with Branch links.

Creating http deep links for your catalog

The easiest way to create deep links for your product feed is to create a "long link" for each product.

  1. Take your base domain, e.g. https://example.app.link
  2. Add your deep link data as query parameters. Be sure to URI encode each query parameter! e.g. https://example.app.link?product_id=123&category=shoes
  3. Add any fallback urls for if the app isn't installed e.g. https://example.app.link?product_id=123&category=shoes&$fallback_url=https%3A%2F%2Fbranch.io%2Funiversal-ads%2F
  4. Finally, add this string, which contains the analytics parameters needed to categorize your data accurately. If you want to add more, go for it! %243p=a_criteo&~feature=paid%20advertising.

Your final link looks like this, and additional query parameters can be added.

https://example.app.link?product_id=123&category=shoes&$fallback_url=https%3A%2F%2Fbranch.io%2Funiversal-ads%2F&%243p=a_criteo&~feature=paid%20advertising

Creating URI scheme deep links for your catalog

Some types of Criteo campaign require URI scheme style deep linking instead of HTTP deep links. Fortunately, you can also create Branch compatible, URI scheme tracking links.

  1. Start with your URI scheme example://
  2. Append open?link_click_id=a-. For example: example://open?link_click_id=a-
  3. Create a JSON blob of your link data, including "~feature":"paid advertising", "$3p":"a_criteo"

For example:

{"~feature":"paid advertising", "$3p":"a_criteo", "~campaign":"My Summer Campaign", "product_id":1234, "category":"shoes"}
  1. Base64 encode your JSON blob.

  2. Append that to your base link, and you're done!

example://link_click_id=a-eyJ+ZmVhdHVyZSI6InBhaWQgYWR2ZXJ0aXNpbmciLCAiJDNwIjoiYV9jcml0ZW8iLCAifmNhbXBhaWduIjoiTXkgU3VtbWVyIENhbXBhaWduIiwgInByb2R1Y3RfaWQiOjEyMzQsICJjYXRlZ29yeSI6InNob2VzIn0=

4b. Static Campaign Deep Links

Just need a single link? It's easy to use the Branch dashboard to create a one-off link. The flow below provides examples of how to create links, but you'll want to consult with your Criteo Solutions Engineer to specify what you require.

  1. First, click Create Ad Link in the top right hand side of the Criteo Partner Manager UI.

    image

  2. First, select an ad format. For App Install or App Engagement campaigns you'll want to select the App Only format.

    To bulk create links for Dynamic Product Ads, select Product Links, which are for shopping or dynamic remarketing campaigns. This will take you to create a Deep Linked Product Feed for Criteo with Universal Links and URI schemes.

    image

  3. If you've select a simple App Engagement link, you'll start with a name for it. Select something that will make it easy to find if you need it later. Your Ad Format and Ad Partner should be selected already, but feel free to choose one if they aren't. It's important that you select the right Ad Partner for analytics later on. Click Configure Options to continue.

    image

  4. This is your chance to add deep link data and analytics tags.

    • Deep Link Data is used to provide the app with product information, so the app can take customers to the right content in the app.
    • Analytics tags are important for later segmentation, so click the Analytics sub tab to add a Channel and Campaign value.

      image

  5. Click Create Link Now, and you have your tracking link! Take this link and give it to your Criteo Solutions Engineer as an example.

    image

4c. Server to Server Tracking Links

If you just need a server to server tracking link, you can use the same flow as Option 2, above.

However, at the end, add the following:

  • &%24s2s=true at the end of your link, so we know it’s a server to server link.

  • Device ID macro &%24idfa= for iOS devices OR &%24aaid= for Android devices.

  • Device OS macro %24os= for IOS or ANDROID.

  • Send IP client’s address via URL parameter or HTTP Header.

    • IP Header to override the IP information on click. e.g. x-ip-override: {IP ADDRESS}.

    • IP URL parameter &device_ip={IP_Address}.

Advanced Configurations

Adding Static Track Transaction

Static Track Transaction is a custom template that replaces the default PURCHASE (Track Transaction) template. You should see STATIC_TRACK_TRANSACTION as an event under the Postback Config in the Criteo Partner Manager UI. You can copy the postback template from STATIC_TRACK_TRANSACTION, and paste it into the PURCHASE postback, replacing the previous postback. Click Save at the bottom of the screen, and you're good to go!

Sending dates for Travel campaigns

Criteo can optimize campaigns based on travel search dates. To report travel search dates to Criteo, follow these steps:

  1. In your app, add custom metadata to your events with keys din and dout, and a date string in format 'YYYY-MM-DD' for the date of the inbound and outbound flight respectively.
  2. In the Branch dashboard, navigate to Postback Config within the Criteo entry of the Ads Partner Manager.
  3. Find the postback you want to edit, and add the following string in the relevant place. For _VIEW_ITEM_ for example, it's another event in the events array.
{"event":"vs","din":<@json>${(custom_data.din)!}</@json>,"dout":<@json>${(custom_data.dout)!}</@json>}

Sending hashed emails

Criteo accepts hashed emails from your ad campaigns. To send hashed emails, please follow the below logic.

  1. In your app, add custom metadata to your events with keys md5_hashed_email, and a value of an MD5 hashed email address. Please do not send unhashed emails to Branch.
  2. In the Branch dashboard, navigate to Postback Config within the Criteo entry of the Ads Partner Manager.
  3. Find the postback you want to edit, and add the following string in the relevant place. This will generally be as another event in the "events" array. Please note that OPEN and INSTALL events do not support this parameter.
{"event":"setHashedEmail", "email":[<@json>${(custom_data.md5_hashed_email)!}</@json>]}

Appendix

Sending non-Branch deep links

Criteo requests all deep links (including non-Branch links) to be sent to their servers upon app open. Branch doesn't provide this by default, so you'll need to update your SDK initialization to support this.

If you use any authentication or login libraries, please ensure you strip out all tokens, passwords and other sensitive information before passing this information to Branch.

To pass the $criteo_deep_link_url to Branch, add this code to your AppDelegate or the relevant Activity/Application. You may already have some of this code inside you files, so simply copy the relevant Branch pieces.

iOS

- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
 restorationHandler:(void (^)(NSArray *))restorationHandler {

    // NOTE: you should sanitize and ensure no sensitive is passed from
    // userActivity.webpageURL.absolutelString.

    [[Branch getInstance] setRequestMetadataKey:@"$criteo_deep_link_url" value:userActivity.webpageURL.absoluteString];
    [[Branch getInstance] continueUserActivity:userActivity];

    // Process non-Branch userActivities here...
    return YES;
}

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication
         annotation:(id)annotation {

    // NOTE: you should sanitize and ensure no sensitive is passed from
    // url.absolutelString.

    [[Branch getInstance] setRequestMetadataKey:@"$criteo_deep_link_url" value:url.absoluteString];
    // Required. Returns YES if Branch link, else returns NO
    [[Branch getInstance]
        application:application
            openURL:url
  sourceApplication:sourceApplication
         annotation:annotation];

    // Process non-Branch URIs here...
    return YES;
}
// repond to universal link URLs
func application(_
        application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([Any]?) -> Void
    ) -> Bool {

        // NOTE: you should sanitize the webpage URL to ensure no sensitive data is passed.
        Branch.getInstance().setRequestMetadataKey("$criteo_deep_link_url", value: userActivity.webpageURL?.absoluteString);
        let branchHandled = Branch.getInstance().continue(userActivity)
        if (userActivity.activityType == NSUserActivityTypeBrowsingWeb) {
            if let url = userActivity.webpageURL,
               !branchHandled {
               // handle other universal links here.
            }
        }

        // Apply your logic to determine the return value of this method
        return true
    }

    // Respond to URL scheme links
    func application(_ application: UIApplication,
                     open url: URL,
                     sourceApplication: String?,
                     annotation: Any) -> Bool {
        // NOTE: you should sanitize the URI scheme to ensure no sensitive data is passed.
        Branch.getInstance().setRequestMetadataKey("$criteo_deep_link_url", value: url.absoluteString)
        let branchHandled = Branch.getInstance().application(application,
                                                             open: url,
                                                             sourceApplication: sourceApplication,
                                                             annotation: annotation
        )
        if(!branchHandled) {
            // If not handled by Branch, do other deep link routing for the Facebook SDK, Pinterest SDK, etc
        }
        return true
    }

Android

Before you initialize in your Application onCreate or Deep Link Activity's onStart.
You will want to persist the value from onCreate, or onNewIntent. mIntentData is a String field defined in the activity.

@Override
protected void onCreate() {
    // NOTE: be sure to remove sensitive / PII data from the intent data coming in.
    mIntentData = this.getIntent().getData().toString();
    // other operations below
}

@Override
public void onNewIntent(Intent intent) {
    // NOTE: be sure to remove sensitive / PII data from the intent data coming in.
    mIntentData = this.getIntent().getData().toString();
    // other operations below
}


Branch.getInstance().setRequestMetadata(""$criteo_deep_link_url"", mIntentData);

...

Branch.sessionBuilder(this)...init();

Identifying users with setIdentity

Branch allows you to identify your users and will send those user identities to Criteo.

The method used to identify users is called setIdentity, and the value you set is called the developer_identity. Set this upon a user login event in your app, and Branch will use it for all subsequent events attributed to that user.

Do not send emails or PII with setIdentity

To respect user privacy, please do not use names, emails or other identifiable information as your developer identity.

Branch and Criteo Event Mapping

Branch supports the full suite of Criteo events. Please talk to your Criteo Solutions Engineer to ensure you've identified the right events for your app.

Important implementation details

  • For events with Branch Event Categorization of "Custom Event," you must name the event as laid out in the below table.

  • For events with Additional Metadata Keys, you must set the Custom Data on the event with a specific key so the postback is configured correctly for you.

For example, for "UI_STATUS" the code snippet looks like this:

iOS

BranchEvent *event     = [BranchEvent customEventWithName:@"UI_STATUS"];
event.customData       = (NSMutableDictionary*) @{
  "ui_status": "subscriber"
  };
event.logEvent() // Log the event.
let event = BranchEvent.customEventWithName("UI_STATUS")
event.customData       = [
  "ui_status": "subscriber"
]
event.logEvent() // Log the event.

Android

new BranchEvent("UI_STATUS")
	    .addCustomDataProperty("ui_status", "subscriber")
	    .logEvent(MainActivity.this);
Branch Event Name Criteo Name Branch Event Categorization Additional Metadata Keys
OPEN View Home & appDeeplink SDK Default $criteo_deep_link_url
INSTALL Install SDK Default None
VIEW_ITEMS View Listing Content Event None
VIEW_ITEM View Product Content Event None
VIEW_CART View Basket Commerce Event None
PURCHASE Track Transaction Commerce Event None
PURCHASE* Static Track Transaction Commerce Event None
ACHIEVE_LEVEL UI Level User Lifecycle Event ui_level
UNLOCK_ACHIEVEMENT UI Achievement User Lifecycle Event ui_achievement
COMPLETE_REGISTRATION Registration User Lifecycle Event None
COMPLETE_TUTORIAL Tutorial Finished User Lifecycle Event None
UI_STATUS UI Status Custom Event ui_status
UI_LOGIN UI Login Custom Event None
SUBSCRIPTION Subscription Custom Event None
LOW_PRIORITY Low Priority Custom Event None
HIGH_PRIORITY High Priority Custom Event None
ABANDONED_BASKET Abandoned Basket Custom Event None

The Static Track Transaction Postback is available as a custom version of the PURCHASE postback. Please see advanced configuration for setup.

Updated about a month ago


Criteo


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.