Ad Partner Integration Testing

Overview

An essential part of the Ad Partners verification process is to confirm that the integration works as expected and we deliver the best user experience. This enables Branch to guarantee the highest quality of Ad Partnership integrations and verify data accuracy.

Verification is a live end-to-end test. You will click a Branch tracking link we provide, install our test application (Branch Monster Factory) on a physical device, and perform a short sequence of in-app actions. Branch registers the resulting events and sends you a postback for each one, which you then check against your own system.

You will need a physical device for each platform you are verifying. Simulators and emulators are not suitable, as install attribution depends on signals only available on real devices.

Once we've provided you with the Click/Impression Tracking URLs via email, please follow the steps in the Set up test app section so we can verify that postback URLs are coming through correctly on your end.

Note: iOS and Android register different events

The iOS and Android versions of Branch Monster Factory do not fire the same conversion events. iOS registers the standard VIEW_ITEM and ADD_TO_CART events. Android registers a Custom Event named after your monster. A single event mapping cannot verify both platforms. If you are verifying both, configure and test each platform separately.

Note: test app versions

The latest versions of Branch Monster Factory vary significantly from older versions. The test app link domain is now monster-factory.app.link; links previously issued on branchster.app.link are no longer used for verification. The app also no longer fires a standard PURCHASE event on either platform, so a postback that matches on PURCHASE will not fire. See Events registered during testing for the current event names.

Test app links

Branch Monster Factory is available in the App Store and Google Play.

iOS

https://apps.apple.com/us/app/branch-monster-factory/id917737838?mt=8

Android

https://play.google.com/store/apps/details?id=io.branch.branchster

Set up test app

To start using the Branch Monster Factory test app:

1. Add the previously emailed tracking link to your system to generate a ClickID and AAID or IDFA specified in the Branch tracking URL, e.g.: https://monster-factory.app.link/XXXXXX?%243p=partner_id&%24aaid={aaid}&%24idfa={idfa}&~click_id={click_id}&~secondary_publisher={secondary_publisher}&parameter1={XXX}&parameter2={YYY}&parameter3={ZZZ}

2. Click on the tracking URL that now contains the filled macro parameters.

3. You'll be redirected to a web page for the Branch Monster Factory application. From here, install and open the app.

4. Initiate the following actions using these specifications:

   1. Install - Install the app from the store you're redirected to, then launch it. The first launch fires the Branch install event.

   2. Open - Close the app and launch it again. This fires the Branch open event.

   3. Event - Complete onboarding, then trigger the conversion event for your platform.

      1. On iOS, create your monster and tap DONE to reach the monster viewer, then tap Share Your Monster!.

      2. On Android, select your monster, then from the Home screen tap Trigger Branch Event followed by Create Event.

Detailed instructions for each platform are provided in Testing on iOS and Testing on Android.

Note: PURCHASE is no longer fired

Earlier versions of Branch Monster Factory fired a standard PURCHASE event. Neither platform fires a Purchase event now. iOS fires the standard VIEW_ITEM and ADD_TO_CART events instead; Android fires a Custom Event named after your monster. See Events registered during testing.

Events registered during testing

During verification, Branch Monster Factory registers four event types on iOS and three on Android. The INSTALL and OPEN events are fired automatically by the Branch SDK on both platforms. The remaining events differ by platform, as described below.

Note that INSTALL fires on the first launch of the app after installation, not when the store finishes downloading it. OPEN fires on every subsequent launch. To see both events cleanly, launch the app once to register the install, close it, then launch it again.

iOS

On iOS, sku and productName are set to the name you gave your monster. currency is always USD. price and revenue are generated by the test app and will vary between runs, so treat them as arbitrary values for the purpose of confirming that the fields arrive populated.

Note: duplicate ADD_TO_CART events on iOS

Completing a share in the iOS share sheet fires a second ADD_TO_CART event. This second event does not carry the commerce parameters listed above. If you see two ADD_TO_CART postbacks with differing payloads during testing, this is expected behavior of the test app and not an integration error.

Android

On Android, the conversion event is a Custom Event named after your monster, so the event name depends on which monster you select during onboarding. There are nine possible monsters, and therefore nine possible event names. All four parameter values are sent as strings.

Configure postback for Custom Event

If your postback matches on a specific event name, it will not fire unless it is configured for the exact name of the monster used in your test. You have two options:

• Configure your postback to receive all Branch Custom Events regardless of name. This requires no advance knowledge of which monster you will select.

• Configure your postback against one or more of the nine event names listed below, then select the matching monster during onboarding.

Before tapping Create Event, you can confirm the event name for your session in the Name field of the Trigger Branch Event overlay. The value shown there is identical to the event name sent to Branch.

Map postbacks against parameter keys

Map your postback against the parameter keys exactly as listed in the tables above, not against the labels shown in the app. Keys are case-sensitive and include spaces where shown.

Also note that Monster Name carries the monster's full name including the color word, which is the same value as the event name. Monster Color carries only the color word from that name.

Note: Monster Exp on Android

On Android, the app displays a monster's experience as XP, but the parameter key sent to Branch is Monster Exp.

Actions that do not register events

The following actions do not fire any tracked Branch Event, and can be disregarded for verification purposes:

• Completing onboarding, on either platform. Selecting, customizing, or naming your monster registers nothing.

• On Android, the Create Branch Link, Share Branch Link, View Branch Event Data, Generate Branch QR Code and Share Branch QR Code challenges on the Home screen. Only Trigger Branch Event fires a tracked event.

On both platforms, the test app attaches monster metadata to the Branch Links it generates in-app. This link data is separate from event data and does not appear in your event postbacks.

Test on iOS

Complete these steps on a physical iOS device, in order. Each step registers one or more of the events listed in Events registered during testing.

Install

Tap the test click URL. iOS prompts you to open the link in the App Store. When you are redirected, tap the Cloud download icon or GET to install Branch Monster Factory.

Once installation finishes, launch the app. The INSTALL event fires when the app first initializes a Branch session, not when the download completes.

Open

Close Branch Monster Factory and launch it again, either from your Home Screen or by tapping Open in the App Store. Every launch after the first fires the OPEN event.

View item

On the Let's create your Branchster screen, use the arrow controls and color swatches to customize your monster, and enter a name in the Name Your Branchster field. Tap DONE.

The monster viewer screen appears. The VIEW_ITEM content event fires when this screen loads, carrying sku (the name you entered), price, and currency. No button triggers this event; reaching the screen is sufficient.

Note: App Tracking Transparency and IDFA

The App Tracking Transparency (ATT) prompt appears when the monster creator screen loads. If you are testing IDFA passthrough, allow tracking when prompted. Because the prompt appears after the app has already initialized its Branch session, the INSTALL and OPEN postbacks for your first launch may not carry an IDFA even when you allow tracking. The VIEW_ITEM and ADD_TO_CART events occur later and will reflect your choice.

Add to cart

From the monster viewer screen, tap Share Your Monster! at the bottom. The ADD_TO_CART commerce event fires immediately, before the share sheet opens.

The iOS share sheet then appears. You can either dismiss it, or complete a share using any option. Completing a share fires a second ADD_TO_CART event without commerce parameters, as described above. The Branch Link for your monster is also displayed in the text field above the button, if you want to copy it directly.

The Info button on the monster viewer screen opens a Branch information screen containing a Check out Device ID Finder link, which can help you confirm the device identifiers associated with your test.

Test on Android

Complete these steps on a physical Android device, in order. Each step registers one or more of the events listed in Events registered during testing.

Install

Tap the test click URL. At the bottom of the page that loads, tap Install Full App. You will be redirected to the Google Play Store, where you should tap Install.

Once installation finishes, launch the app. The INSTALL event fires when the app first initializes a Branch session, not when the Play Store download completes.

Open

Close Branch Monster Factory and launch it again, either from your device or by tapping Open in the Google Play Store. Every launch after the first fires the OPEN event.

Custom Event

On first launch, the app runs a short onboarding flow. Advance through the introductory pages using the arrow control, then select a monster from the list. If you have configured your postback against a specific event name, select the monster matching that name from the table in Configure postback for Custom Event.

Onboarding ends on the Home screen, which shows your monster, its level and XP, and a list of challenges. Tap the Trigger Branch Event challenge.

An overlay slides up showing your monster's Name, Color, Level, and XP. The value in the Name field is the event name that will be sent to Branch. Tap Create Event to fire the event.

Confirm events fired in the app

If an expected postback doen’t arrive, you can check whether the event was fired by the app at all before investigating your own system.

On Android, tap the View Branch Event Data challenge on the Home screen to see a record of events the app has triggered. The app also includes a logs screen showing Branch SDK activity.

On iOS, there is no in-app equivalent. Branch SDK activity is written to the device console at verbose level, which you can view by connecting the device to a Mac and using Console.app.

If an event appears in the app or logs but no postback reaches your system, the issue is likely in postback configuration rather than in the app. Contact us and we can confirm what Branch registered.

Verify the integration

1. Once we register those events, we will pass to you a predefined postback with populated parameters.

2. Please check your system to ensure we passed the correct postback parameters back to you.

3. Notify us via email to verify integration.