Simulating conversions

If you need to simulate Tapstream conversions for testing Deferred Deep Links, Onboarding Links, or for any other purpose, please follow the instructions below.

About Tapstream conversions

Tapstream's attribution engine produces conversions by associating two timelines.

The first timeline, the click timeline, is identified by a first-party cookie on the end-user's device. This cookie is placed or updated whenever the end-user clicks one of your Tapstream campaign links, or whenever they visit a website that has Tapstream's JavaScript installed on it.

The second timeline, the event timeline, is identified by a random number that the Tapstream SDK creates and stores in your app the first time it runs. This timeline is updated whenever the end-user triggers an in-app Tapstream event, like an open, purchase, or custom event.

When the two timelines are associated, the first click in the click timeline gets credit for each event in the event timeline.

Tapstream associates these timelines through a proprietary device identification algorithm. The algorithm uses available hardware IDs, as well as other unique and non-unique device information. Depending on the availability of hardware IDs, Tapstream's algorithm produces results that are between 95% and 100% accurate.

The association is permanent, which makes repeated tests on the same device non-trivial. If the end-user erases their cookies (and therefore the click timeline ID), or deletes the app (and therefore the event timeline ID), the surviving timeline will be orphaned and not be allowed to re-associate.

Tapstream provides a live view of your incoming data. Click on the Live tab in your dashboard to see your test clicks and events being processed in real time.

Simulating a conversion

To simulate conversion, take the following steps:

Step 1: Create a test campaign

Follow the campaign creation documentation to create a new Custom campaign. Call it something obvious, like Test Campaign. Its destination can be any valid URL. Save the campaign and note the campaign link.

For the purposes of this documentation, the example campaign link will be used. Do not use this URL in your own test.

Step 2: Prepare your device

For your test to succeed, your device must be "clean". That means it needs a fresh cookie container, and a fresh app install.

Delete any previous instances of the app from your device or simulator. (Restarting the simulator, or resetting its content and settings, is not sufficient.) Then, erase the cookies from your device's web browser.

Step 3: Set up your live tab to observe your test

Go to the Live tab in your Tapstream dashboard. Apply an IP filter to match your test environment's public-facing IP address. This will make it easier for you to observe your test.

The Live tab, filtered by IP address

Step 4: Trigger the campaign click

On your device's browser, in a new Private Browsing or Incognito tab, open your test campaign URL with the following format. Remember to replace the URL path (the simulate part) with your own:

The __tstest=1 query string key-value pair tells Tapstream to ignore previous click sessions, reducing the chance of errors during testing. Do not use this key-value pair in production.

In your dashboard's Live tab, you will see a campaign click.

The Live tab, showing your campaign click

Note that you can expand each node to see all of the information that Tapstream recorded about it, including custom parameters.

An expanded campaign click node, showing its metadata.

Step 5: Trigger the app event

Now, run your Tapstream-enabled app on your test device. The Tapstream SDK will automatically fire an app install event when you run the app for the first time.

In your dashboard's Live tab, you will see an app event.

The Live tab, showing your event

Step 6: Verify the conversion

In your dashboard's Live tab, click on either the hit session ID or the event session ID. This will drill in to a per-user view of the session. If your test succeeded, you will see a conversion indicator between the hit nodes and event nodes.

The Live tab, filtered by a session. Note that all attributed campaign hits and events are visible.

In your dashboard's Campaigns tab, you will now see a click and an install for your test campaign.

The simulation campaign, showing your click and conversion

Troubleshooting failed simulated conversions

If you're having difficulty simulating conversions, please investigate the following common causes:

  • Using the Tapstream dashboard, check the install count on your test campaign link. If the install count is not incrementing, that means no Tapstream conversion has been created, which means your app will not receive attribution information.
  • Make sure your dashboard's date range is set to include today's date
  • Make sure you're initializing the Tapstream SDK as early as possible in your app's flow.
  • Ensure that your device has been completely wiped of cookies between each attempt, and that you're using a Private Browsing or Incognito tab to perform the attempt
  • Ensure that your app is removed from your device between each attempt. Destroying and re-running simulator instances is not sufficient; you must manually delete the app from the simulator between attempts.
  • If you're using hard-coded hardware IDs to perform the simulation, ensure that the hardware IDs match the expected format of real hardware IDs of that type. For instance, if you use any string that is not a valid UUID for testing with an iOS IDFA, the test may fail.