UPDATE: This SDK has been deprecated as of March 2022 and is no longer supported by our teams.
Contact your technical support at Criteo in case of questions/concerns about your App Integration.

Adding the Criteo App Events SDK

The Criteo Advertiser SDK is distributed as a static library.

CocoaPods

The Events SDK is available as a Pod via Cocoapods (https://cocoapods.org/pods/CriteoEventsSDK/); to use it, add the following to your build target in your Podfile. E.g.:

target 'MyApp' do
    pod 'CriteoEventsSDK'
end

Then run ‘pod install’ in your project directory and open your MyApp.xcworkspace and build

GitHub repository

You can obtain the Event SDK source by cloning the git repository (https://github.com/criteo/ios-events-sdk) and including it into your project manually.

git clone git://github.com/criteo/ios-events-sdk.git

Linking with the AdSupport Framework

The Criteo App Events SDK’s umbrella header includes an @import directive for Apple’s AdSupport module. This module must be linked with your App in order for the Criteo Advertiser SDK to function correctly. If you are compiling with Xcode 5 or higher and your project is configured with Xcode default settings for modules (Enable Modules: Yesand Link Frameworks Automatically: Yes), you don’t need to do anything to enable linkage with the AdSupport module. If you do not have modules enabled, or if you are using an older version of Xcode, simply include AdSupport.framework in your target’s list of Linked Frameworks and Libraries.

Importing the Criteo App Events SDK’s Umbrella Header

You can add it in your app’s precompiled header file (if you have one), or you may explicitly include the umbrella header in each source file that will use the SDK.

#import <CriteoEventsSDK/CriteoAdvertiser.h>

If your application is using Swift, add the umbrella header #importdirective to your Objective-C bridging headerto access the SDK data types from all of your .swift files. If you are not using an Objective-C bridging header, add an import directiveto the top of each swift file that needs to use the Criteo Advertiser SDK.

// Swift import directive for the Criteo Advertiser SDK
import CriteoEventsSDK

Sending Events to Criteo

Events can be sent to Criteo using an instance of EventService. This section explains the process in detail.

Instantiating the Event Service

Events are submitted to Criteo by sending them through an instance of the Event Service class, CRTOEventService. Although you can allocate your own instances of CRTOEventService, most developers should use the shared instance by calling the sharedEventServiceclass method of CRTOEventService.

CRTOEventService* eventService = [CRTOEventService sharedEventService];

let eventService = CRTOEventService.shared()

Customizing the EventService

You need to indicate country and language settings that you are using in your application’s user interface. By default you should get them from the device locale. If you wish to provide customer data along with your events, you can configure the EventService with this information. Use the following code:

eventService.country       = @"US";              // ISO 3166-1 country code(Upper case)
eventService.language      = @"en";              // ISO 639-1 language code(lower case)
eventService.customerId    = @"abc123";          // Customer Identifier

eventService?.country       = "US"                // ISO 3166-1 country code(Upper case)
eventService?.language      = "en"                // ISO 639-1 language code(lower case)
eventService?.customerId    = "abc123"            // Customer Identifier

By default, Criteo uses the app bundle id to track events from your app. You have the option to override this value by explicitly setting an account name. All subsequent events will use the new value, which needs to be whitelisted by Criteo to avoid data loss. As a rule, you should not set the account name without confirmation from your contact at Criteo.

eventService.accountName       = @"com.example.test";  // Override default bundle id

eventService.accountName       = "com.example.test"    // Override default bundle id

If you need to send events with different country, language, account name, or customer settings, you should create new instances of CRTOEventServiceand configure each event service as needed.

Sending Events Using the Send: Method

Create and configure instances of concrete CRTOEventsubclasses, and transmit them to Criteo using the send:method.

CRTOAppLaunchEvent* appLaunch = [[CRTOAppLaunchEvent alloc] init];
[eventService send:appLaunch];

let applaunch = CRTOAppLaunchEvent()
eventService?.send(applaunch)

Deep Link Event

The CRTODeepLinkEvent should be sent to Criteo every time your app receives a URL-based request for the Criteo app campaign.

In iOS, these requests are delivered to your app by calling one of the following methods on your App Delegate: * application:continueUserActivity:restorationHandler: * application:openURL:sourceApplication:annotation: * application:handleOpenURL:

Each time your app receives a call to one of these methods via a deeplink for the Criteo campaign, you must send a CRTODeepLinkEvent containing the requested URL to Criteo.

You only need to send events from methods currently implemented on your App Delegate. Do not add empty implementations of these methods.

Example 1 - application:continueUserActivity:restorationHandler

//Universal Link Example
- (BOOL) application:(UIApplication*)application
continueUserActivity:(NSUserActivity*)userActivity
  restorationHandler:(void (^)(NSArray *))restorationHandler
{
    // Extract the deeplink URL from the NSUserActivity object
    if ( [userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb] ) {
        NSURL* deeplinkURL = userActivity.webpageURL;
        NSString* deeplinkString = deeplinkURL.absoluteString;

        // Instantiate a deeplink event and pass the deeplink to its initializer
        CRTODeeplinkEvent* deeplinkEvent = [[CRTODeeplinkEvent alloc] initWithDeeplinkLaunchUrl:deeplinkString];

        // Send the deeplink event
        [[CRTOEventService sharedEventService] send:deeplinkEvent];

        // Process and handle the universal link
        ...
    }
    return YES;
}

// Universal Link Example
func application(application: UIApplication,
            continueUserActivity userActivity: NSUserActivity,
            restorationHandler: @escaping ([Any]?) -> Void) -> Bool
{
    // Extract the deeplink URL from the NSUserActivity object
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb
    {
        if let deeplinkString = userActivity.webpageURL?.absoluteString
        {
            // Instantiate a deeplink event and pass the deeplink to its initializer
            let deeplinkEvent = CRTODeeplinkEvent(deeplinkLaunchUrl: deeplinkString)

            // Send the deeplink event
            CRTOEventService.shared().send(deeplinkEvent)
        }

       // Process and handle the universal link
        ...
    }
    return true
}

Example 2 - application:openURL:sourceApplication:annotation

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    NSString* deeplinkString = url.absoluteString;
    // Instatiate the deeplink event and pass the deeplink url as a string to the event's initializer
    CRTODeeplinkEvent* deeplinkEvent = [[CRTODeeplinkEventalloc] initWithDeeplinkLaunchUrl:deeplinkString];

    // Send the deeplink event
    [[CRTOEventService sharedEventService] send:deeplinkEvent];

    // Process and handle the deeplink
    ...
}

func application(_ application: UIApplication,
    openURL url: URL,
    sourceApplication: String?,
    annotation: Any?) -> Bool
{
    let deeplinkString = url.absoluteString

    // Instantiate a deeplink event and pass the deeplink to its initializer
    let deeplinkEvent = CRTODeeplinkEvent(deeplinkLaunchUrl: deeplinkString)

    // Send the deeplink event
    CRTOEventService.shared().send(deeplinkEvent)

    // Process and handle the deeplink
    ...
    return true;
}

Example 3 - application:handleOpenURL

Use the following code snippet:

- (BOOL) application:(UIApplication*)application handleOpenURL:(NSURL*)url
{
    NSString* deeplinkString = url.absoluteString;

    // Instatiate the deeplink event and pass the deeplink url as a string to the event's initializer
    CRTODeeplinkEvent* deeplinkEvent = [[CRTODeeplinkEventalloc] initWithDeeplinkLaunchUrl:deeplinkString];

    // Send the deeplink event
    [[CRTOEventService sharedEventService] send:deeplinkEvent];

    // Process and handle the deeplink
    ...
}

func application(application: UIApplication, handleOpenURL url: NSURL) -> Bool
{
   let deeplinkString = url.absoluteString

    // Instantiate a deeplink event and pass the deeplink to its initializer
    let deeplinkEvent = CRTODeeplinkEvent(deeplinkLaunchUrl: deeplinkString)

    // Send the deeplink event
    CRTOEventService.shared().send(deeplinkEvent)

    // Process and handle the deeplink
    ...
    return true
}

Home View Event

CRTOHomeViewEvent should be sent whenever the user reaches the home/welcome screen of the application, either by opening the app or browsing to it. No specific additional data is required.

Use the following code example:

CRTOHomeViewEvent* homeView = [[CRTOHomeViewEvent alloc] init];

// Add extra-data here if required
[[CRTOEventService sharedEventService] send: homeView];

let homeView = CRTOHomeViewEvent()

// Add extra-data here if required
CRTOEventService.shared().send(homeView)

For more information on the adding extra data, see section 5.3 Additional Information

Product View Event

CRTOProductViewEvent should be sent whenever the user browses a specific product/content page, identified by a unique identifier that links it to the product catalog. The below table lists the additional data for this event:

Parameter	Type	Description
productId	string	This is a required field. The values should be a product ID from the catalog that is submitted to Criteo.
price	double	The value should be the unit price of the product.
ci [optional]	string	The value should represent a login or user ID that the developer wants to record for the app launch. Refer to 5.1 User-Level Information.
Start / End date [optional]	date	The check-in, check-out dates in form of YYYY-MM-DD. These are only for Travel vertical business. Refer to 5.4 Dates.

Use the following code example:

// Create an instance of CRTOProduct for the item shown to the user
CRTOProduct* product = [[CRTOProduct alloc] initWithProductId:@"556019227341" price:12.99];

// Create an instance of CRTOProductViewEvent using the product as a parameter
CRTOProductViewEvent* productView = [[CRTOProductViewEvent alloc] initWithProduct:product];

// Send the event
[[CRTOEventService sharedEventService] send:productView];

let productevent = CRTOProductViewEvent()
let product1 = CRTOProduct(productId: "556019227341", price: 12.99)
productevent?.product = product1
CRTOEventService.shared().send(productevent)

Product List View Event

CRTOProductListViewEvent should be sent whenever a user views a list of products or items.

The below table lists the additional data for this event:

Parameter	Type	Description
productId	string	This is a required field. The values should be a product ID from the catalog that is submitted to Criteo.
price	double	The value should be the unit price of the product.
ci [optional]	string	The value should represent a login or user ID that the developer wants to record for the app launch. Refer to 5.1 User-Level Information
Start / End date [optional]	date	The check-in, check-out dates in form of YYYY-MM-DD. These are only for Travel vertical business. Refer to 5.4 Dates.

Use the following code example:

// Create instances of CRTOProduct for the item shown to the user
CRTOProduct* product = [[CRTOProduct alloc] initWithProductId:@"556019227341" price:12.99];
CRTOProduct* product2 = [[CRTOProduct alloc] initWithProductId:@"556019227342" price:1.99];

// Create an array of products
NSArray* products = @[ product, product2 ];

// Create an instance of CRTOProductListViewEvent using the array as a parameter
CRTOProductListViewEvent* listView = [[CRTOProductListViewEvent alloc] initWithProducts:products];

// Send the event
[[CRTOEventService sharedEventService] send:listView];

// Create instances of CRTOProduct for the item shown to the user
let product = CRTOProduct(productId: "556019227341", price:12.99)
let product2 = CRTOProduct(productId: "556019227342", price: 1.99)

// Create an array of products
let products = [ product, product2 ]

// Create an instance of CRTOProductListViewEvent using the array as a parameter
let listView = CRTOProductListViewEvent(products: products)

// Send the event
CRTOEventService.shared().send(listView)

Basket View Event

CRTOBasketViewEvent should be sent whenever a user views items in the shopping cart.

The below table lists the additional data for this event:

Attribute Name	Type	Description
ci [optional]	string	The value should represent a login or user ID that the developer wants to record for the app launch. Refer to 5.1 User-Level Information.
currency	string	The value should a three letter currency code based on ISO 4217.
productId	string	This is a required field. The values should be a product ID from the catalog that is submitted to Criteo.
price	double	The value should be the unit price of the product.
quantity	integer	The value represents the number of units of the product.

Use the following code example:

// Create instances of CRTOBasketProduct to represent items shown to the user
CRTOBasketProduct* product1 = [[CRTOBasketProduct alloc] initWithProductId:@"556019227341"
                                                                     price:100
                                                                  quantity:1];
CRTOBasketProduct* product2 = [[CRTOBasketProduct alloc] initWithProductId:@"556019227342"
                                                                     price:100
                                                                  quantity:1];

// Create an array of basket products
NSArray* products = @[ product1, product2 ];

// Create an instance of CRTOBasketViewEvent and pass the array to its initializer
CRTOBasketViewEvent* basketView = [[CRTOBasketViewEvent alloc] initWithBasketProducts:products
                                                                             currency:@"USD"];

// Send the basket view event
[[CRTOEventService sharedEventService] send:basketView];

// Create instances of CRTOBasketProduct to represent items shown to the user
let product1 = CRTOBasketProduct(productId: "556019227341", price: 100, quantity: 1)
let product2 = CRTOBasketProduct(productId: "556019227341", price: 100, quantity: 1)

// Create an array of basket products
let products = [product1, product2];

// Create an instance of CRTOBasketViewEvent and pass the array to its initializer
let basketView = CRTOBasketViewEvent(basketProducts: products, currency: "USD")

// Send the basket view event
CRTOEventService.shared().send(basketView)

Transaction Confirmation Event

CRTOTransactionConfirmationEvent event should be sent whenever user has completed the purchase.

The below table lists the additional data for this event:

Attribute Name	Type	Description
transactionId	string	The value should represent the transaction ID.
currency	string	The value should be a three letter currency code based on ISO 4217.
productId	string	The values should be a product ID from the catalog that is submitted to Criteo.
price	double	The value should be the unit price of the product.
quantity	integer	This value describes the quantity in the transaction.
deduplication	bool	(Optional) If you track user attribution in-app, this should be true if this transaction is attributed to Criteo
newCustomer	bool	(Optional) If this is the user’s first sale, should be set to true

Use the following code example:

// Create instances of CRTOBasketProduct to represent items sold to the user
CRTOBasketProduct* product1 = [[CRTOBasketProduct alloc] initWithProductId:@"556019227341"
                                                                     price:100
                                                                  quantity:1];
CRTOBasketProduct* product2 = [[CRTOBasketProduct alloc] initWithProductId:@"556019227342"
                                                                     price:100
                                                                  quantity:1];

// Create an array of basket products
NSArray* products = @[ product1, product2 ];

// Create an instance of CRTOTransactionConfirmationEvent and pass the array to its initializer
CRTOTransactionConfirmationEvent* transactionEvent =
    [[CRTOTransactionConfirmationEvent alloc] initWithBasketProducts:products
                                                       transactionId:@"xzy551114432600"
                                                            currency:@"USD"];

// Deduplication parameter (optional)
transactionEvent.deduplication = true;

// Send the basket view event
[[CRTOEventService sharedEventService] send:transactionEvent];

// Create instances of CRTOBasketProduct to represent items sold to the user
let product1 = CRTOBasketProduct(productId: "556019227341", price: 100.0, quantity: 1)
let product2 = CRTOBasketProduct(productId: "556019227342", price: 100, quantity: 1)

// Create an array of basket products
let products = [ product1, product2 ]

// Create an instance of CRTOTransactionConfirmationEvent and pass the array to its initializer
let transactionEvent = CRTOTransactionConfirmationEvent(basketProducts: products,
    transactionId: "xzy551114432600",
    currency: "USD")

// Deduplication parameter (optional)
transactionEvent?.deduplication = true

//Send the event
CRTOEventService.shared().send(transactionEvent)

Data Event

The CRTODataEvent is a generic event that may be used to transmit specific key-value pairs to Criteo.

You should not use this event unless it is directed by of Criteo’s technical representatives. It requires specific configuration to be enabled in Criteo’s systems in order to read this data.

If your account has not been configured with this configuration information, the result of sending this event is undefined.

Use the following code example:

// Create an instance of CRTODataEvent
CRTODataEvent* dataEvent = [[CRTODataEvent alloc] init];

// Create a date value
NSDateComponents* date = [NSDateComponents new];
date.year   = 2015;
date.month  = 12;
date.day    = 31;

// Add the date Key-Value pair to the event
[dataEvent setDateExtraData:date ForKey:@"MyExampleDate"];

// Add a float Key-Value pair to the event
[dataEvent setFloatExtraData:100.0 ForKey:@"MyExampleFloat"];

// Add an integer Key-Value pair to the event
[dataEvent setIntegerExtraData:100 ForKey:@"MyExampleInt"];

// Add a string Key-Value pair to the event
[dataEvent setStringExtraData:@"StringValue" ForKey:@"MyExampleString"];

// Send the event
[[CRTOEventService sharedEventService] send:dataEvent];

// Create an instance of CRTODataEvent
let dataEvent = CRTODataEvent()

// Create a date value
var date = DateComponents()
date.year   = 2015;
date.month  = 12;
date.day    = 31;

 // Add the date Key-Value pair to the event
dataEvent?.setDateExtraData(date, forKey: "MyExampleDate")

// Add a float Key-Value pair to the event
dataEvent?.setFloatExtraData(100.0, forKey: "MyExampleFloat")

// Add an integer Key-Value pair to the event
dataEvent?.setIntegerExtraData(100, forKey: "MyExampleInt")

// Add a string Key-Value pair to the event
 dataEvent?.setStringExtraData("StringValue", forKey: "MyExampleString")

// Send the event
CRTOEventService.shared().send(dataEvent)

Sending Additional Information to Criteo

User-Level Information

If the user is logged into an account in your app, you may provide an identifier related to the user by setting the customerIdproperty on an instance of CRTOEventService.

Use the following code example:

CRTOEventService* eventService = [[CRTOEventService alloc] init];

// Set the user's Customer ID
eventService.customerId = @"abc123";

let eventService = CRTOEventService.shared()

// Set the user's Customer ID
eventService?.customerId = "abc123"

To pass the user’s email address (if they are logged in, for example), assign it to the customerEmailproperty of your CRTOEventServiceinstance.

You also have the option of sending an MD5 hashed email to Criteo directly by setting the customerEmailTypeproperty. Changing its value will clear the customerEmailvalue, which will have to be then be set:

//The customerEmailType defaults to clear text, so setting it is optional if you are not passing in a hashed value
eventService.customerEmailType = CRTOEventServiceEmailTypeCleartext;
eventService.customerEmail = @"user@domain.tld";

//Explicitly send a hashed value
eventService.customerEmailType = CRTOEventServiceEmailTypeHashedMd5;
eventService.customerEmail = @"7d544a8b7db6d512115fd0d2bee3aa3e";

//The customerEmailType defaults to clear text, so setting it is optional if you are not passing in a hashed value
eventService?.customerEmailType = CRTOEventServiceEmailType.cleartext;
eventService?.customerEmail = "user@domain.tld";

//Explicitly send a hashed value
eventService?.customerEmailType = CRTOEventServiceEmailType.hashedMd5;
eventService?.customerEmail = "7d544a8b7db6d512115fd0d2bee3aa3e";

Some apps segment their users, and want to share that segmentation with Criteo. This can be set on a per-event basis using the following code example:

CRTOHomeViewEvent* homeView = [[CRTOHomeViewEvent alloc] init];
homeView.userSegment = 3;
[eventService send:homeView];

let homeView = CRTOHomeViewEvent()
homeView?.userSegment = 3;
eventService.send(homeView)

User Country and Language

If the user changes region or language settings in your app, you should set the values on the instances of CRTOEventServiceused to submit events.

Use the following code example:

// Set a country value
eventService.country  = @"US"; // ISO 3166-1 country code(Upper case)

// Set a language value
eventService.language = @"en"; // ISO 639-1 language code(lower case)

// Set a country value
eventService?.country  = "US" // ISO 3166-1 country code(Upper case)

// Set a language value
eventService?.language = "en" // ISO 639-1 language code(lower case)

Additional Information

Occasionally, you may need to send additional information back to Criteo that has not been explicitly accounted in the data types of Criteo Advertiser SDK. This information is sent in the form of key-value pairs, which may be appended to any event as Extra Data. If you need to send this kind of information back to Criteo along with your events, your Criteo Technical Solutions Engineer will give you instructions about which events to append this information to and how the information should be typed (e.g. date, string, and so on). For more information on how to append extra data to your events, see code samples included in 4.8 Data Event.

Dates

Dates in the Criteo Advertiser SDK are represented with instances of the Foundation NSDateComponentsclass. In order to pass date values with your events, you must first construct an instance of NSDateComponentswith the same date value you have presented to your userin your App’s UI.

Do not attempt to convert, shift, or modify date values before sending them to Criteo. You must send dates exactly as they were presented to your user in order for Criteo’s engine to process them correctly.

For example, if your app presented a product with a start date of ‘2015-01-01’ and an end date of ‘2015-12-31’ to your user, you might use the following code to send a corresponding event to Criteo:

- (NSDateComponents*) dateComponentsForYear:(NSInteger)year
                                      month:(NSInteger)month
                                        day:(NSInteger)day
{
    NSDateComponents* comps = [[NSDateComponents alloc] init];
    comps.year  = year;
    comps.month = month;
    comps.day   = day;
    return comps;
}

- (void) sendProductViewEvent
{
    CRTOProduct* product = [[CRTOProduct alloc] initWithProductId:@"123" price:100.0];
    CRTOProductViewEvent* event = [[CRTOProductViewEvent alloc] initWithProduct:product];
    event.startDate = [self dateComponentsForYear:2015 month:1 day:1];
    event.endDate   = [self dateComponentsForYear:2015 month:12 day:31];
    [[CRTOEventService sharedEventService] send:event];
}

func dateComponentsForYear(year: Int, month: Int, day: Int) -> DateComponents
{
    var comps = DateComponents()
    comps.year = year;
    comps.month = month;
    comps.day = day;

    return comps
}

func sendProductViewEvent()
{
    let productevent = CRTOProductViewEvent()
    let product = CRTOProduct(productId: "123", price: 100.0)
    productevent?.product = product
    productevent?.startDate = dateComponentsForYear(year: 2015, month: 1, day: 1)
    productevent?.endDate = dateComponentsForYear(year: 2015, month: 12, day: 31)
    CRTOEventService.shared().send(productevent)
}

Universal Links & Deeplinks

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

Criteo requires custom native deeplinks to run a App campaign utilizing dynamic creative. These deeplinks use a custom protocol (e.g. sampleadvertiser:// ) and, in most cases, optional parameters. The optional parameters may consist of a path and/or query parameters. (e.g. sampleadvertiser://product/sku123 or sampleadvertiser://product?sku=123).

For iOS, we also strongly recommend Advertisers use Universal Links. For Universal Links, when users click a banner, they’ll be seamlessly redirected to your app without going through Safari. If the app isn’t installed, clicking the App banner will take them to your mobile website in Safari. For more information on Universal Links, please see Apple’s Supporting Universal Links article.

Criteo requires two kinds of Universal Links & custom native deeplinks:

Opens to the homepage of the App.
Opens to each product-details page.

Catalog feed

Overview

A catalog feed is an XML or a CSV file containing product information (name, price, deep link, image link…) that allows Criteo to dynamically generate the product-recommendation banners. Therefore, it is important to keep this file up to date in order for Criteo to show the right data in your banners.

The following points needs to be kept in mind:

Each product must have a unique ID that must be identical to the one passed in the events.
The catalog feed must contain all or at least most of your site’s products.
Recommend image resolution is 300x300 pixels to 400x400 pixels.

Criteo will already have the catalog feed in some instances (i.e. live campaigns on mobile, web, or desktop).

For more information, please request the dedicated guide from your contact.

Other Considerations

Offline Events Retention

Whenever an event cannot be sent to Criteo. (if the device temporarily losses network access, for example), it will be queued to be sent later.

Integration via Criteo SDK (DEPRECATED)

Adding the Criteo App Events SDK

CocoaPods

GitHub repository

Linking with the AdSupport Framework

Importing the Criteo App Events SDK’s Umbrella Header

Sending Events to Criteo

Instantiating the Event Service

Customizing the EventService

Sending Events Using the Send: Method

Deep Link Event

Home View Event

Product View Event

Product List View Event

Basket View Event

Transaction Confirmation Event

Data Event

Sending Additional Information to Criteo

User-Level Information

User Country and Language

Additional Information

Dates

Universal Links & Deeplinks

Catalog feed

Overview

Other Considerations

Offline Events Retention