Branch In-App Events [Android]

Overview

Criteo serves personalized ads to mobile app users that have high probability of clicking through and making a purchase. Criteo technology is based on real-time product recommendation optimization and prediction engines. In order to enable its technology, Criteo needs:

App Events — App events and relevant data correctly captured on your mobile app.
Deep Linking Capability — Product level deep link capabilities in app to take users back to the products they clicked on.
Catalog Feed — A CSV or XML file (called Catalog Feed) containing product information of a large portion of your mobile app’s offers.

This document provides detailed information on the following:

Integration
Required events and parameters
Implementation guidelines

Integration Steps

Steps to Follow	Where to Integrate
Integration Kickoff Call	Criteo & client technical teams
Integration Questionnaire	Client-side
Catalog Feed Integration	Client-side
Criteo Event Implementation	Client-side
Dashboard Configuration	Client-side
Testing Phase	Criteo & client technical teams
App Submission & Release	Client-side
Pre-Launch Checks	Client-side
Campaign Launch	Client-side

App Events & Data

SDK Initialization

Set up and initialize the Branch SDK as recommended by the Branch standard documentation.

Find additional SDK Setup documentation here.

Branch SDK Initialization

Ensure that the Branch SDK is initialized in onStart.

// Branch init
@Override
public void onStart() {
    super.onStart();

    // Branch init
    Branch.getInstance().initSession(new Branch.BranchReferralInitListener() {
        @Override
        public void onInitFinished(JSONObject referringParams, BranchError error) {
            if (error == null) {
                Log.i("BRANCH SDK", referringParams.toString());
            } else {
                Log.i("BRANCH SDK", error.getMessage());
            }
        }
    }, this.getIntent().getData(), this);
}

@Override
public void onNewIntent(Intent intent) {
    this.setIntent(intent);
}

Track appDeeplink Event

@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); // map mIntentData to $criteo_deep_link_url

...

Branch.initSession(...);

Events Implementation in the App

Criteo requires the implementation of the following events:

Event Name	Retail Event Description	Travel Event Description
viewHome	App open / app brought to the foreground.
viewListing	View of a list of products.	View of a list of hotels or flights, usually after a search.
viewProduct	View of a specific product.	View of a specific hotel or flight.
viewBasket	View of shopping basket.	Begin booking process.
trackTransaction	Purchase of one or more products.	Purchase / booking confirmation.

Below is a table of Branch Event Name constants and how they map to Criteo events.

Branch Event	Criteo Event
`BRANCH_STANDARD_EVENT.VIEW_ITEMS`	viewListing
`BRANCH_STANDARD_EVENT.VIEW_ITEM`	viewProduct
`BRANCH_STANDARD_EVENT.VIEW_CART`	viewBasket
`BRANCH_STANDARD_EVENT.PURCHASE`	trackTransaction

Branch Universal Objects

The Criteo integration with Branch relies on the creation of BranchUniversalObjects through the Branch SDK. An array of BranchUniversalObjects should be sent with all events (except app open). BranchUniversalObject represent the product that the user has viewed or purchased and have an associated product id, price, and quantity.

If an equivalent of a required Criteo event is already implemented in the app, then either the BranchUniversalObjects array needs to be implemented in that event or else a new event needs to be created.

View Home

The viewHome event is automatically sent once Criteo has been activated on the app. It is triggered for each new user session.

View Listing

The viewListing event should be triggered on pages displaying product lists like a category page or a search results page for Retail, and travel search results page for Travel. You must include the IDs of the top three products displayed in the list by setting the BranchUniversalObject name to the ID. These IDs must match those passed in the catalog feed. For travel apps, you must send check in (Date1) and check out (Date2) information along with the event.

BranchUniversalObject buo = new BranchUniversalObject()
    .setContentMetadata(
        new ContentMetadata()
            .setSku("item1")
            .setPrice(1.0, CurrencyType.USD)
            .setQuantity(1.5) );

BranchUniversalObject buo2 = new BranchUniversalObject()
    .setContentMetadata(
        new ContentMetadata()
            .setSku("item2")
            .setPrice(2.0, CurrencyType.USD)
            .setQuantity(2.5) );

BranchUniversalObject buo3 = new BranchUniversalObject()
    .setContentMetadata(
        new ContentMetadata()
            .setSku("item3")
            .setPrice(3.0, CurrencyType.USD)
            .setQuantity(3.5) );        

// ...

new BranchEvent(BRANCH_STANDARD_EVENT.VIEW_ITEMS)
    .addContentItems(buo1,buo2,buo3)
    .addCustomDataProperty("sha256_hashed_email","insert_hashed_email_value") // sha256 hashed email
    .addCustomDataProperty("din","2025-05-06") // for travel
    .addCustomDataProperty("dout","2025-05-12") // for travel
    .logEvent(this);

View Product

The viewProduct event should be triggered on all product-details pages. You must include the ID of the product detailed on the page via the BranchUniversalObject name, and send the BranchUniversalObject with the event. It must be the same ID as used in the catalog feed, and must be unique.

BranchUniversalObject buo = new BranchUniversalObject()
    .setContentMetadata(
        new ContentMetadata()
            .setSku("item1")
            .setPrice(1.0, CurrencyType.USD)
            .setQuantity(1.5) ); 

// ...

new BranchEvent(BRANCH_STANDARD_EVENT.VIEW_ITEM)
    .addContentItems(buo)
    .addCustomDataProperty("sha256_hashed_email","insert_hashed_email_value") // sha256 hashed email
    .addCustomDataProperty("din","2025-05-06") // for travel
    .addCustomDataProperty("dout","2025-05-12") // for travel
    .logEvent(this);

View Basket

The viewBasket event should be triggered on the basket-details pages for Retail and when a user begins entering booking details for Travel. You must include the IDs, prices, and quantities of the basket’s products via the BranchUniversalObjects array.

BranchUniversalObject buo = new BranchUniversalObject()
    .setContentMetadata(
        new ContentMetadata()
            .setSku("item1")
            .setPrice(1.0, CurrencyType.USD)
            .setQuantity(1.5) );

BranchUniversalObject buo2 = new BranchUniversalObject()
    .setContentMetadata(
        new ContentMetadata()
            .setSku("item2")
            .setPrice(2.0, CurrencyType.USD)
            .setQuantity(2.5) );

BranchUniversalObject buo3 = new BranchUniversalObject()
    .setContentMetadata(
        new ContentMetadata()
            .setSku("item3")
            .setPrice(3.0, CurrencyType.USD)
            .setQuantity(3.5) );         

// ...

new BranchEvent(BRANCH_STANDARD_EVENT.VIEW_CART)
    .addContentItems(buo1,buo2,buo3)
    .addCustomDataProperty("sha256_hashed_email","insert_hashed_email_value") // sha256 hashed email
    .addCustomDataProperty("din","2025-05-06") // for travel
    .addCustomDataProperty("dout","2025-05-12") // for travel
    .logEvent(this);

Track Transaction

The trackTransaction event should be triggered on order confirmation pages for Retail and booking confirmation pages for Travel. For Retail, you must include a unique transaction ID as well as the IDs, prices, and quantities of the products bought in the transaction via the BranchUniversalObjects array. For Travel, transaction ID is not required.

BranchUniversalObject buo = new BranchUniversalObject()
    .setContentMetadata(
        new ContentMetadata()
            .setSku("item1")
            .setPrice(1.0, CurrencyType.USD)
            .setQuantity(1.5) );

BranchUniversalObject buo2 = new BranchUniversalObject()
    .setContentMetadata(
        new ContentMetadata()
            .setSku("item2")
            .setPrice(2.0, CurrencyType.USD)
            .setQuantity(2.5) );

BranchUniversalObject buo3 = new BranchUniversalObject()
    .setContentMetadata(
        new ContentMetadata()
            .setSku("item3")
            .setPrice(3.0, CurrencyType.USD)
            .setQuantity(3.5) );         

// ...

new BranchEvent(BRANCH_STANDARD_EVENT.PURCHASE)
    .addContentItems(buo1,buo2,buo3)
    .addCustomDataProperty("sha256_hashed_email","insert_hashed_email_value") // sha256 hashed email
    .setTransactionID("transactionID123") // set unique transaction ID
    .setRevenue(500) // purchase revenue
    .addCustomDataProperty("din","2025-05-06") // for travel
    .addCustomDataProperty("dout","2025-05-12") // for travel
    .logEvent(this);

UI Status

The Status should be triggered every time the user opens the app or user status has changed. You must include the status value of the updated status with the event.

new BranchEvent("UI_STATUS")
    .addCustomDataProperty("ui_status", "vip_user")
    .logEvent(MainActivity.this);

UI Level

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

new BranchEvent("ACHIEVE_LEVEL")
    .addCustomDataProperty("ui_level", "42")
    .logEvent(MainActivity.this);

UI Achievement

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

new BranchEvent("UI_ACHIEVEMENT")
    .addCustomDataProperty("ui_achievement", "abc123")
    .logEvent(MainActivity.this);

Extra Data

The Branch Event allows you to add any key-value pairs via the addCustomDataProperty method. To include extra data in the Criteo postback, you must add the extra data in the event. For example, to send the extra data ui_custom in the viewProduct event:

BranchUniversalObject buo = new BranchUniversalObject()
    .setContentMetadata(
        new ContentMetadata()
            .setSku("item1")
            .setPrice(1.0, CurrencyType.USD)
            .setQuantity(1.5) ); 

// ...

new BranchEvent(BRANCH_STANDARD_EVENT.VIEW_ITEM)
    .addContentItems(buo)
    .addCustomDataProperty("ui_custom", "customValue") // add custom parameter
    .logEvent(MainActivity.this);

After this is added to the event, you must also modify the event’s postback configuration in Branch’s dashboard, referencing this extra data parameter, in order for it to be passed in the event.

It is highly recommended to give Branch Dashboard access to your Criteo Technical Solutions Engineer to modify the postback configuration on your behalf.

Customer ID

A Customer ID can be provided in all events. Use the following code snippet to implement:

branch.getInstance(this).setIdentity("userid123");

If the user is logged in to the advertiser’s app, the user ID should be passed.

User ID is an optional parameter and should not be set if the user is logged out or the User ID is unavailable.

Customer ID can be any string, as long as it does not contain any Personally Identifiable Information.

Recommended Events per Vertical

Event Name	Description	Retail	Travel	Classified	Gaming	Streaming Entertainment	Finance	Dating Social	RideHailing
app open/app launch	when user installs the app	Y	Y	Y	Y	Y	Y	Y	Y
home page / App open	when user opens the app or arrives on the home page	Y	Y	Y	Y	Y	Y	Y	Y
view item list / listing	when a user sees list of items/products/offering	Y	Y	Y		Y			Y
view item	when a user sees one specific item/products/offering	Y	Y	Y	Y	Y	Y
add to cart	when a user adds an item/product to the cart	Y	Y
basket	when user is on the basket page	Y	Y
purchase	when user makes a purchase	Y	Y	Y	Y		Y		Y
add to wish list	when a user adds an item/product to the wish list	Y	Y
complete registration / create an account / sign up	when a user creates an account, signs up or completes registration	Y	Y	Y	Y	Y	Y	Y	Y
login	when a user logs in	Y	Y	Y	Y	Y	Y	Y	Y
add payment info	when a user adds payment info	Y	Y				Y		Y
begin checkout	when a user starts the purchase flow	Y	Y				Y
purchase cancelled / purchase refund	when a user cancels a purchase or asks for a refund	Y	Y						Y
generate lead	when a user generates a lead			Y
start trial	when a user starts the trial version of the app				Y	Y	Y	Y
subscribe	when a user subscribes (recurring payment)	Y				Y	Y	Y
select item	when a user has selected content in an app				Y				Y
earn virtual currency	when a user earns virtual currency				Y
level up	when a user passes a level				Y
spend virtual currency/credit	when a user spends virtual currency				Y
tutorial begin	when a user starts the tutorial				Y
tutorial complete	when a user completes the tutorial				Y
unlock achievement	when a user unlocks an achievement				Y
search			Y
video/audio start or media play	when user starts to play media in the app					Y

Testing Process

Once all events have been implemented, you should contact your Criteo representative to begin the testing phase.

Please allow sufficient time (at least a week before) for testing prior to the app submission in order to ensure that the data you are sending is complete.

Criteo requires the following elements:

App build to test the collection of events on Criteo side.
If testing remotely, the GAID of the test device.
Deep link example (homepage & product detail).

AppsFlyer

Adjust

Branch

Kochava

Singular

Branch In-App Events [Android]

Overview

Integration Steps

App Events & Data

SDK Initialization

Branch SDK Initialization

Track appDeeplink Event

Events Implementation in the App

Branch Universal Objects

View Home

View Listing

View Product

View Basket

Track Transaction

UI Status

UI Level

UI Achievement

Extra Data

Customer ID

Recommended Events per Vertical

Testing Process

​Overview

​Integration Steps

​App Events & Data

​SDK Initialization

​Branch SDK Initialization

​Track appDeeplink Event

​Events Implementation in the App

​Branch Universal Objects

​View Home

​View Listing

​View Product

​View Basket

​Track Transaction

​UI Status

​UI Level

​UI Achievement

​Extra Data

​Customer ID

​Recommended Events per Vertical

​Testing Process

Overview

Integration Steps

App Events & Data

SDK Initialization

Branch SDK Initialization

Track appDeeplink Event

Events Implementation in the App

Branch Universal Objects

View Home

View Listing

View Product

View Basket

Track Transaction

UI Status

UI Level

UI Achievement

Extra Data

Customer ID

Recommended Events per Vertical

Testing Process