Search Ads attribution API: where to find the specification of response object (version 3.1)

I love the new Search Ads and I started using the "Search Ads attribution API" in my Xcode project.

Based on WWDC 2016 video I added following Obj-C code:


[[ADClient sharedClient] requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
    if (error) {
        NSLog(@"Request Search Ads attributes failed with error: %@", error.description);
   
        if (error.code == ADClientErrorLimitAdTracking) {
            NSLog(@"Limit Ad Tracking is enabled for this device.");
        }
    }
    else {
        NSLog(@"Search Ads attributes: %@", attributionDetails);
    }
}];


It currently returns test data when using this code on device:

2016-09-29 13:25:09.107 _block_invoke line 48 $ Search Ads attributes: {

"Version3.1" = {

"iad-attribution" = true;

"iad-campaign-id" = 1234567890;

"iad-campaign-name" = CampaignName;

"iad-click-date" = "2016-09-29T11:25:08Z";

"iad-conversion-date" = "2016-09-29T11:25:08Z";

"iad-creative-id" = 1234567890;

"iad-creative-name" = CreativeName;

"iad-lineitem-id" = 1234567890;

"iad-lineitem-name" = LineName;

"iad-org-name" = OrgName;

};

}


However, this object contains different keys than in the WWDC video: while mentioning the same version 3.1:

For example "iad-click-date" vs. "iad-conversion-date". And the 2 "iad-lineitem-***" that are not mentioned in the video.


Where can I find the offical documentation or specification of the response object?


And what do they mean? Most are obvious, but I don't understand the "iad-lineitem-***" keys.

My current guess is that the response always contains the "iad-attribution" key. When it's false, the user hasn't tapped your ad before installing your app, and all other keys are either empty or non-existing.


Any help would be appreciated.

Thank you.

Replies

Hi there,

similar behaviour and doubts here !

The attributionDetails dictionary I''m getting in a device is slightly different:

//Printing description of attributionDetails:

// ▿ Optional<Dictionary<AnyHashable, Any>>

// ▿ some : 1 element

// ▿ 0 : 2 elements

// ▿ .0 : AnyHashable("Version3.1")

// - value : "Version3.1"

// ▿ .1 : 13 elements

// ▿ 0 : 2 elements

// - .0 : iad-keyword

// - .1 : Keyword

// ▿ 1 : 2 elements

// - .0 : iad-adgroup-id

// - .1 : 1234567890

// ▿ 2 : 2 elements

// - .0 : iad-campaign-id

// - .1 : 1234567890

// ▿ 3 : 2 elements

// - .0 : iad-lineitem-id

// - .1 : 1234567890

// ▿ 4 : 2 elements

// - .0 : iad-campaign-name

// - .1 : CampaignName

// ▿ 5 : 2 elements

// - .0 : iad-org-name

// - .1 : OrgName

// ▿ 6 : 2 elements

// - .0 : iad-conversion-date

// - .1 : 2016-10-06T14:53:23Z

// ▿ 7 : 2 elements

// - .0 : iad-creative-name

// - .1 : CreativeName

// ▿ 8 : 2 elements

// - .0 : iad-creative-id

// - .1 : 1234567890

// ▿ 9 : 2 elements

// - .0 : iad-click-date

// - .1 : 2016-10-06T14:53:23Z

// ▿ 10 : 2 elements

// - .0 : iad-attribution

// - .1 : true

// ▿ 11 : 2 elements

// - .0 : iad-adgroup-name

// - .1 : AdGroupName

// ▿ 12 : 2 elements

// - .0 : iad-lineitem-name

// - .1 : LineName


It would be nice if someone at Apple would give us some hints on how to proceed !

Hi Stefat,


In case that no Apple employee will respond, it would be great if we can somehow reverse engineer/understand the response data.

Your output is not the best way of printing a dictionary in a human readable format.

Can you format it similar to mine, so we can easily compare where the differences are?

Thanx

I just realized that this dummy/test data is always returned, even in release builds on a device. Is it also returned by an app-store version of the app, thereby making it useless?

We have added the following check on the repsone, to exclude the dummy data. We log the value searchAdsCampaign to our IAP log.

We have once seen the real value of the campain name.

And a lot of times "No Campaign".

Since we didn't use this value uniquely (i.e. both in lines 11 and 24), we can't give a verdict whether this dummy data doesn't happen in the App Store version.

So in our next update we'll use unique values to see if the dummy data (line 11) is reported from App Store versions.


NSString *searchAdsCampaign = @"";
// Check value for "iad-attribution":
if ([data valueForKey:@"iad-attribution"] != nil) {
    // Check value:
    if ([[data valueForKey:@"iad-attribution"] boolValue]) {
        // Get campaign name:
        if ([data valueForKey:@"iad-campaign-name"] != nil) {
            NSString *campaignName = [data valueForKey:@"iad-campaign-name"];
            // Exclude Apple test data, where value is "CampaignName":
            if ([campaignName isEqualToString:@"CampaignName"]) {
                searchAdsCampaign = @"No Campaign";
            }
            else {
                searchAdsCampaign = campaignName;
            }
        }
        else {
            // Key not found:
            searchAdsCampaign = @"Error";
        }
    }
    else {
        // Value "false":
        searchAdsCampaign = @"No Campaign";
    }
}
else {
    // Key not found:
    searchAdsCampaign = @"Error";
}

Hi, I want to implement this feature in my app for tracking keys that generates downloads from appstore
I want to test this feature in the development build , How can I do that ?
When i was running the code earlier in the iOS10 device it was providing me with dummy data, but now it is returning nil. Can you explain what I am missing this time

I from China.And now I Test This Search Api,The Apple return Me nil and Error is `


Request Search Ads attributes failed with error: Error Domain=ADCientErrorDomain Code=0 "Unable to retrieve attribution details" UserInfo={NSLocalizedDescription=Unable to retrieve attribution details}

` . Now I cannot get Detail Data.Who can help Me?(I have added iAd.framework to my project.)

Thankx.

Do you run it on a device? I was getting same error when running on Simulator. When I run on a device I get back dummy data as others were mentioning in this thread.

We also would like to track effeciency of Apple Search Ads and going to use this API. Would be great if Apple can provide documentation about the returned dictionary format so we know for sure what we will be getting there. Having constant for all keys would help as well.


Also it would be great if dates inside the disctionary can be represented by actual NSDate objects instead of NSStrings.


Thanks in advance!

i am getting this error, too. running on a device with iOS 10.0.2, anyone has any thoughts? thanks!

Figured out. So it generates error on the new iPhone7 but not the old ipad, maybe the new iPhone7 just don't have enough data/information to generate the identifier.

Hi Martijn,


We recently integrated search attribution API code in our app and we are sending the attribution details back to our servers. On opening the app through the search ads, no information is coming on calling [[ADClient sharedClient] requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) method. The attributionDetails dict is nil.. It seems the API if broken for now or i've integrated this in a wrong way. Below is the code as suggested by Apple Docs..

if ([[ADClient sharedClient] respondsToSelector:@selector(requestAttributionDetailsWithBlock:)]) {

[[ADClient sharedClient] requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {

if ((error!=nil) && ([[attributionDetails allKeys] count]>0)) {

[[ADClient sharedClient] addClientToSegments:@[@"installed"] replaceExisting:YES];

if (!_iAdAttributionDetails) {

_iAdAttributionDetails = attributionDetails;

[self sendiAdattributionDetails];

}

}

}];

}


Any help would be much appreciated.


Thanks,

Nishit

I'm having the exact same problem, whether I run on a simulator or a physical device. attributionDetails is nil always.

In case it helps someone here is my code.


        [[ADClient sharedClient] requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
            if (error) {
                DDLogInfo(@"PurchaseHelper: Request Search Ads attributes failed with error: %@", error.description);
              
                if (error.code == ADClientErrorLimitAdTracking) {
                    DDLogInfo(@"Limit Ad Tracking is enabled for this device.");
                }
            } else {
                /* Example seen in dev build
                {
                 "Version3.1" =     {
                 "iad-adgroup-id" = 1234567890;
                 "iad-adgroup-name" = AdGroupName;
                 "iad-attribution" = true;
                 "iad-campaign-id" = 1234567890;
                 "iad-campaign-name" = CampaignName;
                 "iad-click-date" = "2016-10-11T03:58:54Z";
                 "iad-conversion-date" = "2016-10-11T03:58:54Z";
                 "iad-creative-id" = 1234567890;
                 "iad-creative-name" = CreativeName;
                 "iad-keyword" = Keyword;
                 "iad-lineitem-id" = 1234567890;
                 "iad-lineitem-name" = LineName;
                 "iad-org-name" = OrgName;
                 };
                }
                 */
                if (attributionDetails && attributionDetails.allValues.count > 0 && [attributionDetails.allValues[0] isKindOfClass:NSDictionary.class]) {
                    DDLogInfo(@"PurchaseHelper: Search Ads attributes: %@", attributionDetails);
                    NSDictionary *innerDict = attributionDetails.allValues[0];
                    id isAttributed = innerDict[@"iad-attribution"];
                    if (([isAttributed isEqualToString:@"true"] || [isAttributed isEqual:@YES]) && ![[innerDict objectForKey:@"iad-campaign-name"] isEqualToString:@"CampaignName"]) { /
                        DDLogInfo(@"**** DETECTED iAD ATTRIBUTION, MARKING USER PROP");
                        NSString *propVal = @"existent";
                        if ([innerDict objectForKey:@"iad-campaign-name"])
                            propVal = innerDict[@"iad-campaign-name"];
                        [FIRAnalytics setUserPropertyString:propVal forName:@"iad_campaign"];
                    }
                }
            }
        }];

I'm getting the following when running on my iPhone 6S with iOS 10.1 installed:


Request Search Ads attributes failed with error: Error Domain=ADCientErrorDomain Code=0 "Unable to retrieve attribution details" UserInfo={NSLocalizedDescription=Unable to retrieve attribution details}

How the heck am I supposed to test my code?? I am unable to simulate a working call to the API.

How do we get dummy data to test, if we have implemented things correctly.


Thanks & Regards,