Install Attribution APIs

Fingerprint Matching API

Endpoint

(POST) https://api.yozio.com/v2.0/?method=install.attribution.metadata.get

Required Parameters

Name Required Description Example
app_key Yes Log in Yozio Console, click "SDK" on the left sidebar and App Key and Secret Key is available at that page. 99e90a1a-f07a-42db-926d-0be333b726c6
secret_key Yes 3fc0caee-8bef-4ea0-a89e-919b5168a9e6
attribution_method Yes The method used to attribute the install back to the click. At this moment, only fingerprint matching is supported. All available values will be listed in the “Example” column. fingerprinting
os Yes Operating system. All available value will be listed in the “Example” column. ios, android

iOS Parameters

Here are a list of supported parameters when

  • os = ‘ios’
  • attribution_method = ‘fingerprinting’
Name Required Description Example Code
os_version Yes The current iOS Version on your device 9.2
[[UIDevice currentDevice] systemVersion]
hardware Yes Type of iOS Device. The accepted values are listed in the "Example" column iPhone, iPad
[[UIDevice currentDevice] model]
screen_width Yes Screen Width of Device. 320
CGRect screenRect = [[UIScreen mainScreen] bounds];
NSNumber *screenWidth = [NSNumber numberWithDouble: screenRect.size.width];
NSNumber *screenHeight = [NSNumber numberWithDouble: screenRect.size.height];
NSNumber *screen_scale = [NSNumber numberWithDouble: [[UIScreen mainScreen] scale]];
screen_height Yes Screen Height of Device. 568
screen_scale Yes Screen Scale set on Device. 2
device_version No iOS Hardware Version iPhone6,1
[NSString stringWithCString:sys_inf.machine encoding:NSUTF8StringEncoding] 
localizedModel No The model of the device as a localized string “phone” or “tablet”
[[UIDevice currentDevice] localizedModel]
device_name No Name set on iOS Device My iPhone
[[UIDevice currentDevice] name]
country No Device Country United+States
[[NSLocale currentLocale] displayNameForKey:NSLocaleCountryCode value:[[NSLocale currentLocale]
 objectForKey: NSLocaleCountryCode]
country_code No Device Country Code US
[[NSLocale currentLocale]
 objectForKey: NSLocaleCountryCode]
language No Device Language en-US
[[NSLocale preferredLanguages] objectAtIndex:0]
app_name No Bundle Identifier of App com.yozio.ios-dev-app
[[NSBundle mainBundle] bundleIdentifier]
app_version No App Version 1.0
[[[NSBundle mainBundle] infoDictionary] valueForKey:@"CFBundleVersion"]
time_zone_abbr No Time Zone Abbreviation PST
[NSTimeZone systemTimeZone].abbreviation
yozio_udid No Vendor Identifier set on iOS Device 720892D5-A574-4C58-B8D6-B4769178CAE2
if ([[UIDevice currentDevice] respondsToSelector:@selector(identifierForVendor)]) {
    // This is will run if it is iOS6 or above
    return [[[UIDevice currentDevice] identifierForVendor] UUIDString];
}
// before iOS 6, just return ''
return @"";
is_ad_tracking_enabled No Boolean value to check if the app enables the Advertising Tracking 1
+ (BOOL) isAdvertisingTrackingEnabled
{
    id sharedManager = nil;
    Class managerClass = NSClassFromString(@"ASIdentifierManager");
    if (managerClass) {
        SEL sharedManagerSelector = NSSelectorFromString(@"sharedManager");
        sharedManager = ((id (*)(id, SEL))[managerClass methodForSelector: sharedManagerSelector])(managerClass, sharedManagerSelector);
    }
    if (sharedManager) {
        SEL isAdvertisingTrackingEnabledSelector = NSSelectorFromString(@"isAdvertisingTrackingEnabled");
        BOOL enabled = ((BOOL (*)(id, SEL))[sharedManager methodForSelector:isAdvertisingTrackingEnabledSelector])(sharedManager, isAdvertisingTrackingEnabledSelector);
        return enabled;
    }
    return FALSE;
}
idfa No Identifier for advertisers AEBE52E7-03EE-455A-B3C4-E57283966239
+ (NSString *)advertisingIdentifier
{
    id sharedManager = [self sharedManager];
    if (sharedManager) {
        SEL advertisingIdentifierSelector = NSSelectorFromString(@"advertisingIdentifier");
        NSUUID *uuid = ((NSUUID* (*)(id, SEL))[sharedManager methodForSelector:advertisingIdentifierSelector])(sharedManager, advertisingIdentifierSelector);
        return [uuid UUIDString];
    }
    return @"";
}
build No The iOS Version build number. This can be found programmatically by using the code snippet on the right. 13E5181f
+ (NSString *)osVersionBuild
{
    int mib[2] = {CTL_KERN, KERN_OSVERSION};
    size_t size = 0;
    
    // Get the size for the buffer
    sysctl(mib, 2, NULL, &size, NULL, 0);
    
    char *answer = malloc(size);
    sysctl(mib, 2, answer, &size, NULL, 0);
    
    NSString *results = [NSString stringWithCString:answer encoding: NSUTF8StringEncoding];
    free(answer);
    return results;
}

Note:

  • screen_width, screen_height and screen_scale are used to increase fingerprinting accuracy.
  • Some optional parameters are used to increase fingerprinting accuracy; some are used for data segmentation (for example, by providing value for parameter country, you can view how many click occurs by country in your web console dashboard)

Android Parameters

Here is a list of supported parameters when

  • os = ‘android’
  • attribution_method = ‘fingerprinting’
Name Required Description Example Code
os_version Yes Android version 5.1.1
android.os.Build.VERSION.RELEASE
hardware Yes Android device model Nexus 4
android.os.Build.MODEL
device_id No Unique device id 3e9cb633425c76f
Settings.Secure.getString(context.getContentResolver(), Settings.Secure.ANDROID_ID)
device_type No See "Example" phone, tablet
public String getDeviceType(Context context) {
        TelephonyManager manager = (TelephonyManager) context.getSystemService(Context.TELEPHONY_SERVICE);
        if (manager.getPhoneType() == TelephonyManager.PHONE_TYPE_NONE) {
            return "tablet";
        } else {
            return "phone";
        }
    }
app_name No App package name com.yozio.yozio_android _sample_app
packageInfo.packageName
app_version No App version 35.1
packageInfo.versionName
mac_address No Wifi Mac Address 10:68:3f:87:bc:81
wifiManager.getConnectionInfo().getMacAddress()
fingerprint No A string that uniquely identifies this build google/occam/mako:5.1.1/ LMY48T/2237560:user/release-keys
android.os.Build.FINGERPRINT
product No The name of the overall product occam
android.os.Build.PRODUCT
board No The name of the underlying board goldfish
android.os.Build.BOARD
brand No The consumer-visible brand google
android.os.Build.BRAND
device No The name of the industrial design mako
android.os.Build.DEVICE
display No A build ID string meant for displaying to the user LMY48T
android.os.Build.DISPLAY
time No Build time in milliseconds 1441745481000
String.valueOf(android.os.Build.TIME)
manufacturer No The manufacturer of the product/hardware. LGE
android.os.Build.MANUFACTURER
country No The country for this locale United States
Locale.getDefault().getDisplayCountry()
country_code No The country code for this locale US
Locale.getDefault().getCountry()
language No The language code for this Locale en
Locale.getDefault().getLanguage()
time_zone_abbr No The timezone for this Locale PST
TimeZone.getDefault().getDisplayName(false, TimeZone.SHORT, Locale.getDefault())
android_id No A 64-bit number (as a hex string) that is randomly generated when the user first sets up the device and should remain constant for the lifetime of the user's device 3e9cb633425c76f
Settings.Secure.getString(context.getContentResolver(), Settings.Secure.ANDROID_ID)

Note: Optional parameters are used to provide a more accurate matching result.

JSON response

API call succeeds and finds a matched click on a Yozio SuperLink
{
    "status": "ok",
    "body": {
        "short_url": "tb.c.c",
        "probability": 0.7400948543818, // range [0,1]
        "timestamp": 1453404473338
        "metadata": { 
            "promo-code": "XXYYZZ",
            "referrer": "ZZYYXX",
        }
    }
}
API call succeeds and does not find a matched SuperLink click
{
    "status": "ok",
    "body": {
        "probability": -1,
        "timestamp": 1453404473338
    }
}
API call fails
{
    "status": "error",
    "message": "[error message]" // format of error msg may change
}

Note: The responses for iOS and Android share the same format.

100% Matching API (iOS)

Endpoint

(GET) https://api.yozio.com/v2.0/?method=safari.services.matching

Parameters

Name Required Description Example Code
app_key Yes Log in Yozio Console, click "SDK" on the left sidebar and App Key and Secret Key is available at that page. 99e90a1a-f07a-42db-926d-0be333b726c6
secret_key Yes 3fc0caee-8bef-4ea0-a89e-919b5168a9e6
hardware Yes Type of iOS Device. The accepted values are listed in the “Example” column iPhone, iPad, iPod
[[UIDevice currentDevice] model]
os_version No The current iOS Version on your device 9.2
[[UIDevice currentDevice] systemVersion]
screen_width No Screen Width of Device. 320
CGRect screenRect = [[UIScreen mainScreen] bounds];
NSNumber *screenWidth = [NSNumber numberWithDouble: screenRect.size.width];
NSNumber *screenHeight = [NSNumber numberWithDouble: screenRect.size.height];
NSNumber *screen_scale = [NSNumber numberWithDouble: [[UIScreen mainScreen] scale]];
screen_height No Screen Height of Device. 568
screen_scale No Screen Scale set on Device. 2
device_version No iOS Hardware Version iPhone6,1
[NSString stringWithCString:sys_inf.machine encoding:NSUTF8StringEncoding] 
localizedModel No The model of the device as a localized string “phone” or “tablet”
[[UIDevice currentDevice] localizedModel]
device_name No Name set on iOS Device My iPhone
[[UIDevice currentDevice] name]
country No Device Country United+States
[[NSLocale currentLocale] displayNameForKey:NSLocaleCountryCode value:[[NSLocale currentLocale]
 objectForKey: NSLocaleCountryCode]
country_code No Device Country Code US
[[NSLocale currentLocale]
 objectForKey: NSLocaleCountryCode]
language No Device Language en-US
[[NSLocale preferredLanguages] objectAtIndex:0]
app_name No Bundle Identifier of App com.yozio.ios-dev-app
[[NSBundle mainBundle] bundleIdentifier]
app_version No App Version 1.0
[[[NSBundle mainBundle] infoDictionary] valueForKey:@"CFBundleVersion"]
time_zone_abbr No Time Zone Abbreviation PST
[NSTimeZone systemTimeZone].abbreviation
yozio_udid No Vendor Identifier set on iOS Device 720892D5-A574-4C58-B8D6-B4769178CAE2
if ([[UIDevice currentDevice] respondsToSelector:@selector(identifierForVendor)]) {
    // This is will run if it is iOS6 or above
    return [[[UIDevice currentDevice] identifierForVendor] UUIDString];
}
// before iOS 6, just return ''
return @"";
is_ad_tracking_enabled No Boolean value to check if the app enables the Advertising Tracking 1
+ (BOOL) isAdvertisingTrackingEnabled
{
    id sharedManager = nil;
    Class managerClass = NSClassFromString(@"ASIdentifierManager");
    if (managerClass) {
        SEL sharedManagerSelector = NSSelectorFromString(@"sharedManager");
        sharedManager = ((id (*)(id, SEL))[managerClass methodForSelector: sharedManagerSelector])(managerClass, sharedManagerSelector);
    }
    if (sharedManager) {
        SEL isAdvertisingTrackingEnabledSelector = NSSelectorFromString(@"isAdvertisingTrackingEnabled");
        BOOL enabled = ((BOOL (*)(id, SEL))[sharedManager methodForSelector:isAdvertisingTrackingEnabledSelector])(sharedManager, isAdvertisingTrackingEnabledSelector);
        return enabled;
    }
    return FALSE;
}
idfa No Identifier for advertisers AEBE52E7-03EE-455A-B3C4-E57283966239
+ (NSString *)advertisingIdentifier
{
    id sharedManager = [self sharedManager];
    if (sharedManager) {
        SEL advertisingIdentifierSelector = NSSelectorFromString(@"advertisingIdentifier");
        NSUUID *uuid = ((NSUUID* (*)(id, SEL))[sharedManager methodForSelector:advertisingIdentifierSelector])(sharedManager, advertisingIdentifierSelector);
        return [uuid UUIDString];
    }
    return @"";
}
build No The iOS Version build number. This can be found programmatically by using the code snippet on the right. 13E5181f
+ (NSString *)osVersionBuild
{
    int mib[2] = {CTL_KERN, KERN_OSVERSION};
    size_t size = 0;
    
    // Get the size for the buffer
    sysctl(mib, 2, NULL, &size, NULL, 0);
    
    char *answer = malloc(size);
    sysctl(mib, 2, answer, &size, NULL, 0);
    
    NSString *results = [NSString stringWithCString:answer encoding: NSUTF8StringEncoding];
    free(answer);
    return results;
}

JSON Response

The response from Yozio backend is in HTML format since in SFSafariViewController you couldn’t read the response directly from your app, it like another application, but you app could be activated by using the deep link, Yozio returned HTML will help you with this part. Here’s the response will happen.

  • short_url
  • probability
    • Yozio matching probability, if your app don’t get this, you can contact Yozio Customer Success to enable it.
  • metadata
    • Key value pairs associated with your Yozio SuperLink. This will include metadata attached via any of the Yozio supported methods (ie static, dynamic, Sublink API).

API call succeeds and finds a matched click on a Yozio SuperLink by using 100% accuracy matching

    Status code - 200

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<!DOCTYPE html>
<html>
<head>
<script type="text/javascript">
    window.onload = function() {
        location.href = "your-app-scheme://yozio/?metadata%5Binvite%5D=derek&metadata%5Btest%5D=testing&metadata%5B0%5D=4321&metadata%5Banc%5D=qwer&short_url=g.c.c&probability=1";
    }
</script>
</head>
<body></body>
</html>

API call succeeds and finds a matched click on a Yozio SuperLink by using fingerprint matching

    Status code - 200

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<!DOCTYPE html>
<html>
<head>
<script type="text/javascript">
    window.onload = function() {
        location.href = "your-app-scheme://yozio/?metadata%5Binvite%5D=derek&short_url=g.c.c&probability=0.899999";
    }
</script>
</head>
<body></body>
</html>

API call succeeds and does not find a matched SuperLink click

    Status code - 200

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<!DOCTYPE html>
<html>
<head>
<script type="text/javascript">
    window.onload = function() {
        location.href = "your-app-scheme://yozio/?probability=-1";
    }
</script>
</head>
<body></body>
</html>

API call failed with errors

    Status code - 200

1
Parameter app_key is missing.

100% Matching API (Android)

Endpoint

https://api.yozio.com/v2.0/?method=install.attribution.with.google.play.referrer

Parameters

All the parameters should be in post body.

Name Required Description Example Code
app_key Yes Log in Yozio Console, click "SDK" on the left sidebar and App Key and Secret Key is available at that page. 99e90a1a-f07a-42db-926d-0be333b726c6
secret_key Yes Android version 3fc0caee-8bef-4ea0-a89e-919b5168a9e6
referer Yes Query string that been received from google play market which constructed by Yozio link, this query string will always include __y=1 __ysurl=g.c.c&__y=1&hello=world
hardware Yes Device model Nexus 9
android.os.Build.MODEL
device_type No The accepted values are listed in the “Example” column phone, tablet
public String getDeviceType(Context context) {
        TelephonyManager manager = (TelephonyManager) context.getSystemService(Context.TELEPHONY_SERVICE);
        if (manager.getPhoneType() == TelephonyManager.PHONE_TYPE_NONE) {
            return "tablet";
        } else {
            return "phone";
        }
    }
app_name No App package name com.yozio.yozio_android_sample_app
packageInfo.packageName
app_version No App version 35.1
packageInfo.versionName
mac_address No Wifi Mac Address 10:68:3f:87:bc:81
wifiManager.getConnectionInfo().getMacAddress()
fingerprint No A string that uniquely identifies this build google/occam/mako:5.1.1/ LMY48T/2237560:user/release-keys
android.os.Build.FINGERPRINT
product No The name of the overall product occam
android.os.Build.PRODUCT
board No The name of the underlying board goldfish
android.os.Build.BOARD
brand No The consumer-visible brand with which the product/hardware will be associated, if any google
android.os.Build.BRAND
device No The name of the industrial design mako
android.os.Build.DEVICE
display No A build ID string meant for displaying to the user LMY48T
android.os.Build.DISPLAY
time No Build time in milliseconds 1441745481000
String.valueOf(android.os.Build.TIME)
manufacturer No The manufacturer of the product/hardware. LGE
android.os.Build.MANUFACTURER
country No The country code for this locale United States
Locale.getDefault().getDisplayCountry()
country_code No The country for this locale US
Locale.getDefault().getCountry()
language No The language code for this Locale en
Locale.getDefault().getLanguage()
time_zone_abbr No The timezone for this Locale PST
TimeZone.getDefault().getDisplayName(false, TimeZone.SHORT, Locale.getDefault())
android_id No A 64-bit number (as a hex string) that is randomly generated when the user first sets up the device and should remain constant for the lifetime of the user's device 3e9cb633425c76f
Settings.Secure.getString(context.getContentResolver(), Settings.Secure.ANDROID_ID)

JSON response

Cases Sample
API call succeeds
{
    "status": "ok"
}
API call fails
{
    "status": "error",
    "message": "[error message]" // format of error msg may change
}