About YozioIOSSDK

Important!!: Check out our full integration documentation at here. This guide will only help you get configuration set up.

There are three files included in the pod:

• YozioDefaults.plist
• libYozio.a
• Yozio.h

Note: There are 3 keys in YozioDefaults.plist.

1. logging_enabled allows you to turn on or off Yozio logging.
   1. request_timeout allows you to modify the max time the Yozio SDK will wait for the Yozio backend to retrieve metadata
      1. use_sf_safari_view_controller ensures that safari's view controller is used by Yozio.

Swift Support

In order to use the Yozio SDK with Swift, you will need a bridging header file that allows Swift apps to use Objective C code.

You can simply add the Yozio SDK to your app, and Xcode will prompt you to create a Bridging Header. Confirming here will automatically create a bridging header, Name-Of-Your-Module-Bridging-Header.h.

Alternatively, you can create your own Bridging-Header.h file.

In the bridging header file, you will need to include the Yozio.h file

#import <Yozio.h>

Please refer to this article for more information on bridging header files.

Install tracking and new install metadata callback configuration

Include Yozio.h to your AppDelegate.m by pasting the following inside the didFinishLaunchingWithOptions in your AppDelegate.m, and by passing your_app_key and your_app_secret_key in parameters.

//Configures the Yozio SDK. 
//Must be called when your app is launched and before any other method.
//Use the actual keys for your app per the instructions above
- (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;
}

This block of code will try to match a SuperLink click event and retrieve metadata from the Yozio Cloud (back end). If you only want to track new install by Yozio, you could pass nil to newInstallMetaDataCallback.

For any user who installed from an interaction with a Yozio SuperLink, Yozio will persist the metadata received from Yozio back end. If you wish, you can access a users new install metadata anytime through the following methods

[Yozio getNewInstallMetaDataAsHash];
[Yozio getNewInstallMetaDataAsUrlParameterString];

Need a code example? You can view a real code example in our iOS Sample App, Yozio Console > SDK > click Download iOS Sample App

Verify iOS new install metadata return

There are two ways you can choose to verify install tracking setup:

1. via a real iPhone device connected to Xcode
2. via a iPhone simulator

Warning: Safari on a iOS 8.x simulator will not verify correctly. There is a bug with the user agent which will impact the Yozio iOS matching mechanism

Verification Steps: (It is critical that the steps are followed in the order below)

1. Ensure logging is enabled by going to YozioDefaults.plist, and changing logging_enabled to true.
2. Delete the app from your mobile device.
3. Use an existing test SuperLink, or create a new one.
4. Click the test SuperLink
5. Install the app from Xcode and open it.
6. Check your debug console for information. You should see "data from new install" and a list of parameters.

If you'd like, you can verify click and install attribution for your test SuperLink in the Yozio Console > SuperLinks > Organic Links > "name of your test SuperLink" (the Yozio dashboards are updated every, on average, every 15 minutes).

100% New Install Match Accuracy

Yozio iOS SDK v2.0 and newer supports 100% install match accuracy for iOS 9. We leverage the use of SFSafariViewController to keep track of users that install your app through a Yozio SuperLink. 100% Match Accuracy only applies to users that meet the following prerequisites:

• The end user must be on iOS 9, using Safari, and not in "Private Mode"
• The time gap between the click and first app launch cannot be more than 30 days

In order to implement 100% Match Accuracy...

1. Add the SafariServices.framework to your project (Build Phase -> Link Binary With Libraries -> +).
2. Use [Yozio handleOpenURL:url] to deliver new install metadata and track deep link clicks
3. In YozioDefaults.plist, set use_sf_safari_view_controller to "YES"

Configure iOS deep link redirect url in Yozio Console

Login to the Yozio Console > Settings > Default Redirect Settings and make sure your deep link flag for your device is turned on. Then, enter your deep link URL.

Alternatively you may modify redirect settings for individual SuperLinks; just navigate to the link end page from SuperLinks > Organic Links on the left panel of the Yozio Console and click Edit to configure a particular SuperLink.

Implement iOS deep link tracking code and metadata util

Add [Yozio handleOpenURL:url] in your AppDelegate.m. To access Yozio deep link metadata implement the util function below to parse metadata from query string.

 - (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
             sourceApplication:(NSString *)sourceApplication
                     annotation:(id)annotation
                     {   
                            // Track deep links
                               [Yozio handleOpenURL:url];

                                     // This is a util function to parse metadata from query string,
                                        // and it will filter out Yozio internal parameters which key starts
                                           // with "__y".
                                              NSDictionary *metaData = [Yozio getMetaDataFromDeeplink:url];

                                                    NSLog(@"Got meta data from deep link: %@", metaData);

                                                          // Add your custom code to handle meta data.
                                                             return YES;
                     }
                     ```

                     Yozio will persist the last clicked deep link metadata locally. To get this metadata you can use the following helpers:

                     ```
                     [Yozio getLastDeeplinkMetaDataAsHash];
                     [Yozio getLastDeeplinkMetaDataAsUrlParameterString];
                     ```

### Verify deep link setup and metadata return

On a test device that has your iOS app installed, click on the Yozio SuperLink for your app that has metadata associated with it. Your app should open and in the Xcode debug console, you will be able to see the metadata captured. 

If you have deployed the Yozio deep link tracking code, the Yozio Console will also have recorded a deep link event for the SuperLink which was clicked. 

## Yozio Custom Events

### Tracking Yozio Default Events

Yozio has two default events: 

Default Event Name | iOS Tracking Code   
------------------ | ----------------- 
signup             | `[Yozio trackSignup];` 
payment            | `[Yozio trackPayment:12.50];`

Fire this tracking code anytime a conversion for the event occurs. 

### Tracking Custom Events

#### Step 1: Register an event to track

You can register any downstream event you'd like to track conversion for with Yozio. By default Yozio provides the events Signup & Payment, so there is no need to register those events. To register more downstream post install event to track with Yozio: 

1. Login to the [Yozio Console](http://console.yozio.com) 
2. Go to **Settings** > **Downstream Events** 
3. Add your event 
  * Enter the event name (32 character limit, no special characters) 
    * Enter an event description (optional) 
      * Click "Register Downstream Event" 

       You will receive confirmation that the event was created and your custom event will now be listed on the Downstream Events page. In addition, your custom event will now be available as a selection on all dashboards of the Yozio Console so that you may view campaign attribution results.

#### Step 2: Integrate iOS tracking code

Place the tracking code into your app to fire anytime the event occurs. Please see the Yozio iOS Sample App (Login to the Yozio Portal > "Settings" > "iOS" > click to download "iOS Sample App") for a real code example. Format the tracking code as follows:

[Yozio trackCustomEventWithName:@"Your-Custom-Event-Name" andValue:nil];

Here is an iOS code example (please see the Yozio sample apps for more code examples):

// Fire Custom Event - a more generic example // A user just invited 10 friends. [Yozio trackCustomEventWithName:@"invite" andValue:@"10"];

#### Step 3: Verify iOS downstream event tracking setup
Verify setup by hitting the run button in Xcode and you should see more Yozio Console logs. If you ever want to silence the logs from Yozio go to `YozioDefaults.plist`, and change `logging_enabled` to `false`.