> ## Documentation Index > Fetch the complete documentation index at: https://developers.criteo.com/llms.txt > Use this file to discover all available pages before exploring further. # Branch In-App Events [Android] > Implement Criteo in-app events for Android using the Branch SDK. ## 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](https://docs.branch.io/pages/apps/android/#initialize-branch). #### Branch SDK Initialization Ensure that the Branch SDK is initialized in `onStart`. ```java theme={null} // 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 ```java theme={null} @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. ```java theme={null} 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. ```java theme={null} 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. ```java theme={null} 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. ```java theme={null} 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. ```java theme={null} 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. ```java theme={null} 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. ```java theme={null} 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: ```java theme={null} 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. Image It is highly recommended to [give Branch Dashboard access](https://docs.branch.io/pages/dashboard/access-level/) 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: ```java theme={null} 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).