Using Onboarding Links with the Tapstream PhoneGap SDK

First, integrate the latest PhoneGap plugin.

Integration instructions for PhoneGap

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:

        // Read some data from this json object, and modify your application's behavior accordingly


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": "",
      "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": ""
  "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": "",
      "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.