Handling New Installs on iOS

Overview

In this article, we’ll go over how to set up the Yozio SDK in your app to handle users who have just installed your app through a Yozio SuperLink.

The New Install of Yozio SuperLinks covers users who do not have your app and click on a Yozio SuperLink. There are a number of ways you can handle the users who do not have your app, but the new install case can be divided into two core pieces of functionality:

  • Install Attribution
  • Data passing

Prerequisites

  • Have the Yozio SDK added to your app
  • Have access to the Yozio Console for your SuperLinks

Install Attribution on iOS

The first part of handling users who do not have the app is attributing installs to a click on a Yozio SuperLink that happened earlier. This is the most important step, as the tracking and data passing cannot occur without a correct attribution. We tie installs to clicks using a unique identifier for the SuperLink, the short URL (e.g. a.b.c is the short URL for r.rivendell.com/a.b.c), so that you can track on our Yozio Dashboard the activity on your SuperLinks and the campaigns that they represent.

Attribution using the iOS SDK

The Apple App Store does not allow for direct data passing from a click event to the app install. A subtle consequence of this is that we have to be creative in how we attribute a new app install to the past click event that triggered it. Yozio provides many methods for attributing installs to clicks. They call into two categories:

  • 100% accurate match
  • Fingerprint match

Yozio recommends you deploy all methods of attribution. Then, by default, when we are not able to make a 100% match, we will automatically fallback to fingerprint matching. Make sure you’ve implemented the attribution methods correctly, however, as you’ll run into errors if you’ve missed any steps.

Fingerprint Matching

With fingerprint matching, Yozio uses a variety of parameters that we collect when the install happens to calculate the likelihood that a particular click event was responsible for the new install later down the road.

The iOS SDK function initializeWithAppKeyAndSecretKey accomplishes this attribution. The function should be called in the AppDelegate method didFinishLaunchingWithOptions; if the SDK detects that this launch is a result of a new install, the SDK will make a call to our backend to find a click event that is likely to have been responsible for this install. Then, if it finds a match, our backend will return all the relevant information (the responsible Yozio SuperLink and all its metadata) back to the app. Here is some sample code demonstrating how you place the initializeWithAppKeyAndSecretKey function call.

1
2
3
4
5
6
7
8
9
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
   [Yozio initializeWithAppKey:@"your_app_key"
                     secretKey:@"your_secret_key"
    newInstallMetaDataCallback:^(NSDictionary *metaData) {
       NSLog(@"Got Meta Data from new install: %@", metaData);
   }];
   return YES;
}

Finally, we have a flag in the YozioDefaults.plist, request_timeout, that defines the amount of time that this method will wait for our servers to respond with an attribution. We’ve worked hard to make our server response time as quick as possible (typically under 50ms); however if you are in a non-US region or if you have slow internet connection, it is possible that the SDK will throw an http error if the SDK does not receive a response in the time set by this flag.

100% Matching using SFSafariViewController

One of the weaknesses of fingerprint matching is that ultimately, we cannot always be 100% sure that a particular install event is indeed a result of a particular click event. In order to address this, we’ve provided an option that will leverage the power of SFSafariViewController, introduced in iOS 9,to guarantee when an install event is tied to a click event earlier.

In order to implement 100% Matching using SFSafariViewController,

  • Add the SafariServices.framework to your project (Build Phase -> Link Binary With Libraries -> +).
  • Call [Yozio handleOpenURL:url] to deliver new install metadata and track deep link clicks
  • In the YozioDefaults.plist, set use_sf_safari_view_controller to YES
  • Enable deep linking and enter your custom scheme URL. You can either do this by editing individual SuperLinks or editing the default redirect settings.

Once you’ve completed these steps, call the Yozio initialize function (the same one used for fingerprint matching; it will now use 100% matching using SFSafariViewController instead).

1
2
3
[Yozio initializeWithAppKey:@"your_app_key"
                     secretKey:@"your_secret_key"
    newInstallMetaDataCallback:^(NSDictionary *metaData) {}];

There are a couple of restrictions when using 100% matching using SFSafariViewController

Your end user must be on iOS 9, using Safari to open your SuperLinks, and not in "Private (Incognito) Mode" The time gap between the click and first app launch cannot be more than 30 days

100% Matching using IDFA

The second method of 100% matching we provide for your users on iOS is 100% matching using IDFA. When a user deep links into any of our customers’ apps with Yozio integrated and with IDFA passed in, the Yozio SDK will link a cookie to the user’s IDFA. We use this cookie that we attach whenever a user clicks on a Yozio SuperLink in their browser, to achieve 100% install attribution in other apps. Assuming the user does not clear the cookies of their browser, we’ll be able to attribute the install that happens on the device.

There’s no extra action required to implement 100% matching using IDFA; if you’ve integrated the Yozio SDK, we’ll use our network to try and find an attribution to your install.

Verifying New Install Attribution on iOS

To verify on iOS, simply click on a Yozio SuperLink and install the app through XCode. Once the app is opened, you should see logs in your XCode output that verify that the install is being properly tracked (make sure you have Yozio’s logging enabled in YozioDefaults.plist). Specifically, look for the following logs:

1
2
https://sdk-api.yozio.com/?app_key=YOUR_APP_KEY&method=sdk.app.install
YozioApi HTTP Response - {"status":"ok","body":{"yozio_probability":number_between_0_and_1,"__ysurl":"test_short_url_would_be_here","timestamp":events_unix_timestamp, "your_metadata":"would_be_here"}}

If you’d ever like to turn off the Yozio logs, simply set the YozioDefaults.plist value logging_enabled to NO. Note that if you report any issue to [email protected], it will greatly expedite the resolution of your case if you re-enable logging_enabled beforehand.

New Install Data Passing

Passing data into the app after a new install occurs independently of tracking, but can only be done after an attribution has been made. Once Yozio knows a particular install event is tied with a click event, the metadata associated with the click can be properly parsed. As such, you will need to implement Install Attribution before implementing Data Passing into the app.

New Install Data Passing using the iOS SDK

If you’ve successfully implemented Install Attribution on iOS, the initialize function,

1
2
3
4
5
[Yozio initializeWithAppKey:@"your_app_key"
                     secretKey:@"your_secret_key"
    newInstallMetaDataCallback:^(NSDictionary *metaData) {
       NSLog(@"Got Meta Data from new install: %@", metaData);
   }];

will populate the NSDictionary metadata with the metadata it received from the attribution. This initialize function allows you to implement your own metadata callback function. In this callback function, you have the option of handling the metadata however you’d like, whether that be calling a ViewController, or simply logging a successful data pass (Hint: implement a personalized onboarding experience for the user!)

Additionally, the new install metadata will be persisted locally on the device, and it will forever (as long as the user does not uninstall the app) be available for your app to use. Call the functions

1
2
[Yozio getNewInstallMetaDataAsHash]
[Yozio getNewInstallMetaDataAsUrlParameterString]

to access it.

Verifying New Install Data Passing on iOS

See “Verifying New Install Handling on iOS”. You will be able to see the metadata in the XCode logs. Specifically, look for the following logs

1
YozioApi HTTP Response - {"status":"ok","body":{"yozio_probability":0.99,"__ysurl":"test_short_url_would_be_here","timestamp":events_unix_timestamp, "your_metadata":"would_be_here" }}