Using Onboarding Links with the Tapstream Android SDK

First, integrate the latest Android SDK.

Integration instructions for Android

Retrieving the user's attribution data

The Tapstream SDK gives you a mechanism for receiving a callback that will contain everything Tapstream knows about the user's timeline, including any links the user clicked on or websites of yours they visited before running the app. This feature is only available to paid accounts.

If you want to customize the behavior of your application based on the user's source campaign, click parameters, or other pre-install behavior, Onboarding Links allow you to asynchronously request this data from the SDK.

  • Do not block on this mechanism. In most cases, a response is available to the SDK almost immediately, but in exceptional circumstances, it may take up to 10 seconds for the SDK to receive a response or return nil.
  • Initialize the Tapstream SDK as soon as possible. For best results, your app should initialize Tapstream as early as possible in the app session.

Here's how it works:

import org.json.JSONArray;
import org.json.JSONException;

...

Tapstream tracker = Tapstream.getInstance();
ApiFuture<TimelineSummaryResponse> timelineFuture = tracker.getTimelineSummary();
timelineFuture.setCallback(new Callback<TimelineSummaryResponse>(){

    @Override
    public void success(TimelineSummaryResponse result) {

        if (result.isEmpty()){
            // No timeline data was available
        } else {
            String latestDeeplink = result.getLatestDeeplink();
            if(latestDeeplink != null){
                // Modify your application's behavior based on this deeplink.

                // Note: You will want to record that you've done this so as not to repeatedly
                // redirect this user.
            }
        }
    }

    @Override
    public void error(Throwable reason) {
        // The service is not available. You can interrogate reason for more info.
    }
});

Available fields on the TimelineSummaryResponse object are:

  • latestDeeplink, the latest deep link URL this user visited
  • latestDeeplinkTimestamp, a long (in milliseconds since the unix epoch) representing the time that this user click on the deep link.
  • deeplinks, a list of all deeplinks this user has clicked on
  • campaigns, a list of unique campaigns this user has visited
  • hitParams, a map of all parameters from all hits (campaign visits) in this user's timeline
  • eventParams, a map of all parameters from all events in this user's timeline

Advanced Usage

If you need more detailed information about the user's activity, you can retrieve their full timeline using the lookupTimeline method:

import org.json.JSONArray;
import org.json.JSONException;

...

Tapstream tracker = Tapstream.getInstance();
ApiFuture<TimelineApiResponse> timelineFuture = tracker.lookupTimeline();
timelineFuture.setCallback(new Callback<TimelineApiResponse>(){

    @Override
    public void success(TimelineApiResponse result) {

        if (result.isEmpty()){
            // No timeline data was available
        } else {
            try {
                JSONObject timeline = result.parse();
                // Read some data from this json object, and modify your application's
                // behavior accordingly.
                // ...
                // ...
            } catch (JSONException e){
                // There was a deserialization error. This shouldn't ever happen.
            }
        }
    }

    @Override
    public void error(Throwable reason) {
        // The service is not available. You can interrogate reason for more info.
    }
});

JSON API

See Tapstream's API Documentation for more information.

An example JSON response from the timeline summary API might look like this:

{
    "latest_deeplink": "trending://stocks/",
    "latest_deeplink_timestamp": 1476989678682,
    "campaigns": ["example-campaign"],
    "deeplinks": ["trending://something-else/", "trending://stocks/"],
    "hit_params": {"user_id": "abc123"},
    "event_params": {}
}

An example JSON response for the same user from the timeline lookup API might look like this:

{
  "hits": [
    // This is an array of all hits (e.g. campaign clicks and website visits) associated with this user.
    {
      "custom_parameters": { // All custom query string parameters
        "__deeplink": "trending://stocks/", // If available, the deeplink destination you defined for this platform
        "user_id": "abc123"
      },
      "created": 1383695050683,
      "ip": "199.21.86.54",
      "app": "tapfoliotrending",
      "session_id": "2b3d397e-4674-11e3-a2a0-525400f1a7ad",
      "tracker": "example-campaign", // The slug of the campaign link
      "dest_url_platform": "ANY",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 7_0_3 like Mac OS X) AppleWebKit/537.51.1 (KHTML, like Gecko) Version/7.0 Mobile/11B511 Safari/9537.53",
      "referrer": "",
      "device_specific_hardware_ids": {
        "ios_idfa": "141E8456-3D20-46D1-92F8-8EE0728BE7BF"
      },
      "id": "2b3d608f-4674-11e3-a2a0-525400f1a7ad",
      "dest_url": "http://itunes.apple.com/us/app/stocks-trending-stocks-at-a-glance/id512068016?ls=1&mt=8"
    }
  ],
  "events": [
    // This is an array of all in-app events associated with this user.
    {
      "profile_model": "iPhone5,1",
      "profile_gmtoffset": 4294938496,
      "profile_resolution": "640x1136",
      "created": 1383695183000,
      "ip": "199.21.86.54",
      "app": "tapfoliotrending",
      "profile_sdkversion": "2.4",
      "session_id": "df9b7f5d-ca9c-4ef3-a0b9-1e66795eef5e",
      "package_name": "com.paperlabs.TapfolioTrending",
      "tracker": "ios-trending-open", // The slug of the event
      "profile_os": "iPhone OS 7.0.3",
      "profile_vendor": "Apple",
      "device_specific_hardware_ids": {
        "ios_idfa": "142D8456-4E70-46D1-92F8-8EE0728BE7BF",
        "ios_secure_udid": "EAAD91D5-EAEA-40BC-A244-13A3D7748F95"
      },
      "app_name": "Trending",
      "id": "7a1f50ce-4674-11e3-a312-525400d091e2",
      "profile_locale": "en_US",
      "profile_platform": "iOS"
    },
  ]
}

If you wish to simulate conversions to test this functionality, please refer to the documentation on simulating Tapstream conversions.

Deep linking when the user doesn't already have the app

Onboarding Links allow you to deeplink your users to different parts of your app, even if they didn't already have it. Parse the JSON response and look for the custom parameter called __deeplink. This parameter's value is the deeplink destination that your user would have been sent to when clicking your campaign link, had they already had the app.

Check out the documentation on deferred deep linking for more information on how to configure your Tapstream campaigns to pass a __deeplink parameter to new users.