Using Onboarding Links with the Tapstream iOS SDK

First, integrate the latest iOS SDK.

Integration instructions for iOS

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:

let tracker = TSTapstream.instance() as TSTapstream
TSTapstream.instance().getTimelineSummary() { (response: TSTimelineSummaryResponse?) in
    if response == nil || response!.failed() {
        print("Timeline request failed!")
        return
    }

    if let dl = resp!.latestDeeplink {
        let ts = resp!.latestDeeplinkTimestamp

        // Parse the deeplink URL and modify your application's behavior accordingly

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

Available fields on the TSTimelineSummaryResponse 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:

let tracker = TSTapstream.instance() as TSTapstream
TSTapstream.instance().lookupTimeline() { (response: TSTimelineApiResponse?) in
    if response == nil || response!.failed() {
        print("Timeline request failed!")
        return
    }

    let events = response!.events
    let hits = response!.hits

    for hit in hits {
        let h = hit as! NSDictionary
        print(h["tracker"])
        // Read some data from this json object, and modify your application's behavior accordingly
    }
}

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.