Overview

This version of the Criteo SDK incorporates the Google Advertising ID ( http://developer.android.com/google/play-services/id.html ) which requires the Google Play Services SDK to be added in your app.

Including Criteo SDK Library

The Criteo SDK library can be used with Android Studio and Maven, Gradle, Ivy, and Eclipse. This section contains procedures that will help you include the Criteo SDK library.

The Criteo Events SDK is available via:

JCenter

The Events SDK is available as an AAR via JCenter; to use it, add the following to your build.gradle.

repositories {
    jcenter()
}

dependencies {
    implementation 'com.criteo.android:events-sdk:1.1.7'
}

Please find dependency snippets for Maven, Ivy and Gradle at this link: https://bintray.com/criteo/mobile/android-events-sdk

Alternatively, you can directly download the .aar from JCenter and include it into your app as a new module.

https://bintray.com/bintray/jcenter?filterByPkgName=android-events-sdk

GitHub repository

You can obtain the Event SDK source by cloning the git repository ( https://github.com/criteo/android-events-sdk)) and including it into your app as a new module:

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

Using Android Studio & Gradle

To use the Criteo SDK with Android Studio and Gradle based projects:

1. To add it as a new module, go to File -> New -> New Module.
2. Click Import .JAR/.AAR package.
3. Select the supplied . AAR package.
4. Give a name to the module (such as criteo-ads-sdk). The new module is added in the Project View pane.
5. Open the build.gradle of your app.
6. Within the dependencies {} parentheses, by adding the follow line add the module as a local dependency and replace the module-name with the one you specified above. compile project(':module-name') After syncing the project with Gradle, the module in your app is ready for use.

Using Eclipse

To use the Criteo SDK with Eclipse based projects:

1. From the . AAR package, extract the .JAR.

2. To extract, rename the .AAR to .ZIP.

3. To extract the classes.JAR file, use a decompression tool.

4. Rename classes.JAR (such as criteo-ads-sdk.jar).

5. Add it to your app's libs folder.

   Create a libs folder if it does not exist.

6. Right click the . jar file and select Build Path -> Add to Build Path.

Once added to the build path, the SDK is available to use inside your app.

Add Settings to Application Manifest

To allow permissions for the Criteo Tag SDK, add the following code to AndroidManifest.xml after the </application> tag:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

To enable your app to use the Google Play Services and access the user identifier, add the following code within the application tag:

<meta-data android:name="com.google.android.gms.version"
           android:value="@integer/google_play_services_version" />

Sending Events to Criteo

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

Importing the SDK

To import the Criteo library, use the following code at the top of your files:

import com.criteo.events;
import com.criteo.events.product;

Instantiating the EventService

Events are submitted to Criteo by sending them through an instance of the EventService class. The same instance can be reused throughout the application.

EventService criteoEventService = new EventService(getApplicationContext());

Customizing the EventService

You need to indicate the user's country and language settings that is being used in your application's user interface.

If you wish to provide customer data along with your events, you can configure the EventService with this information:

// Country must follow the ISO 3166-1 alpha-2 code and should be in uppercase
// Language must follow the ISO ISO 639-1 and should be in lowercase
criteoEventService.setCountry("FR");
criteoEventService.setLanguage("fr");

By default, Criteo uses the app package name 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.

// Overrides the default account name with the provided value
criteoEventService.setAccountName("com.example.test");

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

Sending Events to Criteo

Inside your application, every time an event retargeting happens, you should execute a new Criteo event, and send it through the appropriate EventService. There are a number of different events that can be sent which are explained in this section.

Home View Event

HomeViewEvent should be sent whenever the user reaches the home/welcome screen of the application, either by opening the app or browsing. No specific additional data is required for this event.

Use the following code example:

// Create the home view event
HomeViewEvent homeView = new HomeViewEvent();

// Add extra data here if required.
// Send the event to Criteo
criteoEventService.send(homeView);

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

Product View Event

ProductViewEvent 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:

Use the following code example:

// Create the product view event
ProductViewEvent productView = new ProductViewEvent(productId, price);

// Set currency (Optional)
productView.setCurrency(Currency.getInstance("USD"));

// Set start and end dates (Optional)
// The dates sent should be the ones that are visible in the app to the user
productView.setStartDate( new GregorianCalendar(2015, Calendar.JANUARY, 1));
productView.setEndDate( new GregorianCalendar(2015, Calendar.JANUARY, 8));

// Add extra data here if required
// Send the event to Criteo
criteoEventService.send(productView);

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

Product List View Event

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

The below table lists the additional data for this event:

Use the following code example:

// Create the product objects
Product product1;
product1 = new Product("123456788", 100.05);
Product product2;
product2 = new Product("45678912345", 55.67);
Product product3;
product3 = new Product("321987456", 12.34);

// Create the ProductListViewEvent
ProductListViewEvent productListView = new ProductListViewEvent(product1, product2, product3);

// Set currency (Optional)
productListView.setCurrency(Currency.getInstance("USD"));

// Set start and end dates (Optional)
// The dates sent should be the ones that are visible in the app to the user

productView.setStartDate( new GregorianCalendar(2015, Calendar.JANUARY, 1));
productView.setEndDate( new GregorianCalendar(2015, Calendar.JANUARY, 8));

// Add extra data here if required
// Send the event to Criteo
criteoEventService.send(productListView);

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

Basket View Event

BasketViewEvent should be sent a user views items in the shopping cart. The below table lists the additional data for this event:

Use the following code example:

// Create the basket product objects
BasketProduct basketProduct1;
BasketProduct basketProduct2;
basketProduct1 = new BasketProduct("555555555", 34.54, 2);
basketProduct2 = new BasketProduct("4443332211", 23.05, 3);

// Other constructor can be used. Please refer to API reference.
BasketViewEvent basketView = new BasketViewEvent(basketProduct1, basketProduct2);

// Set currency (Optional)
productListView.setCurrency(Currency.getInstance("USD"));

// Set start and end dates (Optional)
// The dates sent should be the ones that are visible in the app to the user
basketView.setStartDate( new GregorianCalendar(2015, Calendar.JANUARY, 1));
basketView.setEndDate( new GregorianCalendar(2015, Calendar.JANUARY, 8));

// Add extra-data here if required
// Send the event to Criteo
criteoEventService.send(basketView);

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

Transaction Confirmation Event

TransactionConfirmationEvent should be sent when user has completed the purchase. The below table lists the additional data for this event:

Use the following code example:

// Create the transaction confirmation event
String transactionId = "12345654321";
BasketProduct basketProduct1;
BasketProduct basketProduct2;
basketProduct1 = new BasketProduct("555555555", 34.54, 2);
basketProduct2 = new BasketProduct("4443332211", 23.05, 3);
TransactionConfirmationEvent txConfirmation = new TransactionConfirmationEvent(transactionId, basketProduct1, basketProduct2);

// Set currency (Optional)
txConfirmation.setCurrency(Currency.getInstance("USD"));

// Set start and end dates (Optional)
// The dates sent should be the ones that are visible in the app to the user. Time zone conversion does not need to be done.
txConfirmation.setStartDate( new GregorianCalendar(2015, Calendar.JANUARY, 1));
txConfirmation.setEndDate( new GregorianCalendar(2015, Calendar.JANUARY, 8));

// Add extra-data here if required
// Example: If you track advertiser attribution in-app, you can inform Criteo that this sale is a result of a running campaign:
// True if this sale is attributed to Criteo, false otherwise
txConfirmation.setDeduplication(true);

// Example: If you track first sale events in-app, you can pass that data to Criteo
txConfirmation.setNewCustomer(true);

// Send the event to Criteo
criteoEventService.send(txConfirmation);

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

Data Event

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

Use the following code example:

// Create an instance of DataEvent
DataEvent dataEvent = new DataEvent();

// Create a date value
GregorianCalendar date = new GregorianCalendar(2015, Calendar.JANUARY, 8);

// Add the date key-value pair to the event
dataEvent.addExtraData("MyExampleDate", date);

// Add a float key-value pair to the event
dataEvent.addExtraData("MyExampleFloat", 100.0);

// Add an integer key-value pair to the event
dataEvent.addExtraData("MyExampleInt", 100);

// Add a string key-value pair to the event
dataEvent.addExtraData("MyExampleString", "StringValue");

// Send the event
criteoEventService.send(dataEvent);

Sending Additional Information to Criteo

User-level Information

If the user logs into an account in your app, you may provide an identifier related to the user by setting thecustomerIdproperty on an instance of EventService.

Use the following code example:

// Set the customer's identifier
criteoEventService.setCustomerID("abc_123");

You can pass in the user’s email as cleartext, which will be hashed before being sent to Criteo. You also have the option of passing in the MD5 hashed value directly:

// Pass the customer's email address as clear text
criteoEventService.setEmail("user@domain.tld");

// Explicitly send a hashed email address
criteoEventService.setEmail("7d544a8b7db6d512115fd0d2bee3aa3e",
    EventService.EmailType.HASHED_MD5);

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:

// Create the home view event
HomeViewEvent homeView = new HomeViewEvent();

// Sets the user's segment based on their activity in the app
homeView.setUserSegment(3);

// Send the event to Criteo
criteoEventService.send(homeView);

User Country and Language

If the user changes the application settings, you should change the country and language fields set in the EventService instance.

Use the following code example:

// Set country based on the user's settings
criteoEventService.setCountry("US");

//Set language based on the user's settings
criteoEventService.setLanguage("es");

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.

Any event can have additional Extra Data. The data is added as a key-value pair to the event using the addExtraData() method. The data types that can be added as extra data include: string, int, GregorianCalendar, and float.

In addition to the normal events, there is a Data Event that is not specifically designed for any particular user action but just to attach extra data.

For more information on how to append extra data to events, see code samples included with the DataEvent documentation.

Dates

Dates in the Criteo Advertiser SDK are represented with instances of theGregorianCalendarclass. In order to pass date values within your events, you must first construct an instance ofGregorianCalendarwith the same date value you have presented to your user in the user interface of your app.

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:

// Create the product view event
ProductViewEvent productView = new ProductViewEvent(productId, price);

// Set currency (Optional)
productView.setCurrency(Currency.getInstance("USD"));

// Set start and end dates
// The dates sent should be the ones that are visible in the app to the user
productView.setStartDate( new GregorianCalendar(2015, Calendar.JANUARY, 1));
productView.setEndDate(new GregorianCalendar(2015, Calendar.DECEMBER, 31));

// Send the event to Criteo
criteoEventService.send(productView);

App 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 Android, we also strongly recommend Advertisers use Android App Links. Android App Links are HTTP URLs that bring users directly to specific content in your Android App. Android App Links can drive more traffic to your app, help you discover which app content is used most, and make it easier for users to share and find content in an installed app. For more information on App Links, please see Android Studio’s Add Android App Links article.

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

1. Opens to the homepage of the App.
2. 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.

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

Other Considerations

Offline Events Retention

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