AppsFlyer iOS Integration Guide

A guide to implementing Criteo solutions in AppsFlyer.

Overview

This tutorial will explain how to integrate your application with Criteo.

Catalog Feed

Please provide Criteo with a product feed in an XML or a CSV file containing product information (name, price, deeplink, image link...). This will allow Criteo to dynamically generate the product recommendation banners, thus it is critical to keep this file up-to-date for Criteo to show the right data in your banner.

Please take note of the following points:

  • Each product must have a unique ID that is identical to the ID passed in the events.
  • The catalog feed must contain all or at least most (> 80%) of your site's products
  • Recommended image resolution is 300x300 pixels to 400x400 pixels

Events & Data

SDK Initialization and SDK Attribution Tracking

The following code snippet should be placed at the app launch:

[AppsFlyerTracker sharedTracker].appsFlyerDevKey = @"appsFlyerDevKey";
[AppsFlyerTracker sharedTracker].appleAp/pID = @"983352090"; // appstore app id
[AppsFlyerTracker sharedTracker].currencyCode = @"USD";
[AppsFlyerTracker sharedTracker].customerUserID = @"customerid";

[[AppsFlyerTracker sharedTracker] trackAppLaunch];

The following code snippet should be placed at deep link launch:

// Reports app open from a Universal Link for iOS 9
- (BOOL) application:(UIApplication *)application continueUserActivity:(NSUserActivity
*)userActivity restorationHandler:(void (^)(NSArray *_Nullable))restorationHandler
{
[[AppsFlyerTracker sharedTracker] continueUserActivity:userActivity
restorationHandler:restorationHandler];
return YES;
}
// Reports app open from deep link for iOS 8 or below
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
sourceApplication:(NSString*)sourceApplication annotation:(id)annotation
{
[[AppsFlyerTracker sharedTracker] handleOpenURL:url sourceApplication:sourceApplication
withAnnotation:annotation];
return YES;
}

Events Implementation in the App

Criteo requires the implementation of the following events:

Event Name Description
viewHome App open / app brought to the foreground
viewListing View of a list of products
viewProduct View of a specific product
viewBasket View of shopping basket
trackTransaction Purchase of one or more products
User Status User status within the game i.e. subscriber, registered, guest
User level Highest level reached by user (optional for non-gaming clients)
Tutorial Completed User has completed tutorial (optional for non-gaming clients)
Achievement unlocked User has reached a key milestone within a game (optional for non-gaming clients)

The viewHome and appDeeplink events are automatically sent once Criteo has been activated in AppsFlyer dashboard

You need to ensure to initialize the AppsFlyer SDK as indicated above for app launches via standard open and deep link. The initialization process and call to trackAppLaunch shouuld happen for each session.

2. viewListing

The viewListing event should be fired on pages displaying product list such as category page or search-result page. You need to include the IDs of the first three products displayed in the list by setting the event item name to their IDs. These IDs must match with the IDs in the catalog feed.

Use the following code snippet to implement:

[[AppsFlyerTracker sharedTracker] trackEvent:@"af_list_view" withValues:@{
            AFEventParamCurrency: @"USD", @"product": @[@"4", @"5", @"6"],
            AFEventParamDateA: @"2015-05-05",
            AFEventParamDateB: @"2015-05-06"}];
3. viewProduct

The viewProduct event should be fired on all product-details pages. You need to include the ID of the product detailed on the page via the event item name and send the ID with the event. This ID must match with the ID in the catalog feed.

Use the following code snippet to implement:

[[AppsFlyerTracker sharedTracker] trackEvent:AFEventContentView
            withValues : @{
                    AFEventParamCurrency: @"USD",
                    AFEventParamContentId: @"4"}];
4. viewBasket

The viewBasket event should be fired on the basket-details pages. You must include the IDs, prices, and quantities of the basket's products via the event items array.

Use the following code snippet to implement:

[[AppsFlyerTracker sharedTracker] trackEvent:@"af_view_cart" withValues:@{
        AFEventParamCurrency: @"USD",
        @"product":@[
                @{AFEventParamContentId: @"5",
                AFEventParamPrice: @10.2,
                AFEventParamQuantity: @1},
                @{AFEventParamContentId:@"6",
                AFEventParamPrice: @1.1,
                AFEventParamQuantity: @2},
                @{AFEventParamContentId:@"7",
                AFEventParamPrice: @9.3,
                AFEventParamQuantity: @5}]}];
5. trackTransaction

The trackTransaction event should be fired on sales confirmation pages. You need to include a unique tranasction or order ID as well as the product IDs, prices and quantitys of the products purchased in the transaction via the event items array.

Use the following code snippet to implement:

[[AppsFlyerTracker sharedTracker] trackEvent:AFEventPurchase withValues :
        @{AFEventParamCurrency: @"USD",
                AFEventParamReceiptId: @"transactionuid",
                AFEventParamRevenue: @58.9,
        @"product":@[
                @{AFEventParamContentId: @"5",
                        AFEventParamPrice: @10.2,
                        AFEventParamQuantity: @1},
                @{AFEventParamContentId:@"6",
                        AFEventParamPrice: @1.1,
                        AFEventParamQuantity: @2},
                @{AFEventParamContentId:@"7",
                        AFEventParamPrice: @9.3,
                        AFEventParamQuantity: @5}],
        AFEventParamDateA: @"2015-05-05",
        AFEventParamDateB: @"2015-05-06"}];
6. UI Level

The uiLevel event should be triggered every time user opens the app or levels up. You need to include the level value of the new incremental level reached.

Use the following code snippet to implement:

[[AppsFlyerTracker sharedTracker] trackEvent:AFEventLevelAchieved withValues: @{AFEventParamLevel: @"35"}];
7. UI Status

The uiStatus should be triggered every time user opens the app or user status changes. You need to include the status value of the updated status with the event.

Use the following code snippet to implement:

[[AppsFlyerTracker sharedTracker] trackEvent:@"af_user_status" withValues: @{@"ui_status": @"registered"}];
8. UI Achievement

The achievement event should be triggered every time the user unlocks a new achievement. You need to include the name of the achievement.

[[AppsFlyerTracker sharedTracker] trackEvent:AFEventAchievementUnlocked withValues:@{AFEventParamDescription:@"secret_key"}];

Hashed Email for Cross-Device Targeting

Clients should send Criteo hashed email address of the app user when available to enable cross-device targeting. Following are the steps to generate hash of an email address: - Convert all characters to lower case - Remove any blank spaces - Convert to UTF-8 - Hash using MD5 algorithm

Following is the sample code for sending hashed email to AppsFlyer.

[[AppsFlyerTracker sharedTracker] setUserEmails:@[ 
            @"email1@mydomain.com", 
            @"email2@mydomain.com" 
            ] 
            withCryptType:EmailCryptTypeMD5 
];

Dashboard configurations

  1. Go to Configuration > Integrated Partners appsflyer_integratedpartner

  2. Select Criteo by either scrolling down to Criteo or by searching for Criteo in the filter field appsflyer_criteopartner

  3. Select Enable checkbox to enable viewHome event for Criteo appsflyer_enablecriteo

  4. Under App Settings, enable re-targeting campaign measurement appsflyer_enablemeasurement

Event mapping

  1. Choose send Criteo All in-app events appsflyer_inappevents

  2. Click + Click to add in app event mapping and map the events as shown below appsflyer_inappmappings

  3. Click Save & Close

Deep linking consists of a hyperlink that links to a specific, generally searchable, or indexed piece of content on an app.

Deep linking is usually implemented with a custom protocol (e.g. {{deeplinkurl}}:) and optional parameters. These optional parameters may consist of a path or a query, and are completely flexible. (e.g. {{deeplinkurl}}fashion_product1 or {{deeplinkurl}}?fashion_product1).

Criteo requires two kinds of deep links that:

  1. Opens the app on the homepage
  2. Opens the app on each product detail page

Following are some guidelines provided by AppsFlyer on deep linking implementation:

SDK version must be 2.5.1.13 and newer

In addition to the standard integration, you only need to call the SDK’s handleOpenURL from the app delegate openURL method. Please check section 6.6 in the iOS integration guide.

In order to test it, you can use the custom media source with the supported macros found here.

Tracking in AppsFlyer

AppsFlyer and Criteo support server to server click tracking. The format is:

http://app.appsflyer.com/id123456789?pid=criteo_int&advertising_id={aaid}&c={campaign_name}&is_retargeting=true&redirect=false&af_click_lookback=30d&af_reengagement_window=30d

The same query string parameters should be added to the app deep link. A completed deep link will look like:

com.myapp://?pid=criteo_int&c={campaign_name}&is_retargeting=true&af_click_lookback=30d&af_reengagement_window=30d

Query string parameters accepted are:

Parameter Description
pid Network name, always set to "criteo_int"
is_retargeting Denotes retargeting campaign, always set to "true"
idfa Apple Id For Advertising
c Campaign name
redirect Redirect to appstore, always set to "false"
af_click_lookback Click lookback windows, primarily used by app reinstall campaings. Can be left to default (7d) or changed to 30d
af_reengagement_window Standard reengagement window. Should be set to 30d to match Criteo retargeting window

Verification

You should contact Criteo to start the testing phase as soon as the events are implemented.


Criteo will require the following elements:

  • Pieces of implemented code for each event.
  • App build to test the collection of events on Criteo side.
  • If remote testing, the idfa of the device used to test the events.