What’s new in AdAttributionKit

Hey everyone, I’m Mike, an engineer on the App Store Engineering team. And today I’ll share some new AdAttributionKit features we’ve built for developers of advertised apps. Hi, I’m Yuchi, I’m an engineer on the Commerce Engineering team, and today I'll share new features for configuring attribution and receiving new data if you’re a consumer of postbacks.

Here at Apple, we believe privacy is a fundamental human right. That’s why we built AdAttributionKit from the ground up to help advertisers measure the success of their ad campaigns while preserving the privacy of users. I’ll start with a summary of how AdAttributionKit works.

An AdAttributionKit flow consists of three different parties. An ad network is responsible for creating and delivering an ad payload to a publisher app.

The publisher app will handle displaying an advertisement for the advertised app.

And finally, the advertised app measures engagement from actions that people take from within their app. These actors each play a role at different points in an end-to-end flow of AdAttributionKit.

An end-to-end flow begins with an ad network creating an ad payload for an app. The ad network then delivers an ad payload to the publisher app, and the publisher app will display an advertisement to someone.

Someone can interact with an ad by either viewing it or tapping on it, which leads to either an install or re-engagement conversion.

An install conversion occurs when someone installs your app from the App Store or an alternative app marketplace as a result of interacting with an ad.

Re-engagement conversions occur when someone engages with an ad for an app they already have installed, taking them into the advertised app directly.

Once a conversion has occurred, the advertiser measures interactions and engagement that people perform inside of their app.

After the conversion window has ended, the data representing the conversion and engagement measurements are transmitted in the form of a postback back to the ad network. And that completes an end-to-end flow of AdAttributionKit.

As a quick recap if you’re not familiar, AdAttributionKit launched with iOS 17.4 and included support for install conversions. We added re-engagement support with iOS 18.

For a refresher on getting started with AdAttributionKit, check out our WWDC24 session, “Meet AdAttributionKit.” With that review in mind, we’re excited to show you new features we've built that enhance different parts of the end-to-end flow.

If you’re a developer of an advertised app, I’ll show you some powerful new features around measurement and testing flows you can use in your app.

If you’re an ad network or a downstream consumer of postback data, Yuchi will share enhancements we’ve built for your attribution flows and new data in postbacks.

We've divided this talk into four parts.

First, I’ll cover conversion tags, which enables you to measure overlapping re-engagement conversions inside of your app.

Yuchi will then give a breakdown of how you can customize attribution rules for your app and discuss new geography data we’ve added to postbacks.

And finally, I’ll wrap up with how to test your AdAttributionKit implementation with new testability in the iOS Settings app.

Let’s dive into how you can measure overlapping conversion windows.

Let’s focus on the re-engagement flow inside of our end-to-end diagram.

Up until iOS 18.3, your app can only have one active re-engagement conversion at any point in time.

As of iOS 18.4, your app can now have multiple active re-engagement conversion windows at the same time.

Your app can also receive conversion tags, which is like a bookmark for a conversion. You can use conversion tags to specify, which re-engagement conversion to update. Let’s review a scenario where you would use conversion tags in your app.

As a developer, you may run multiple re-engagement campaigns to promote different sales you’re offering to customers in your app.

A customer could see an ad promoting a discounted product in your app and decide to tap on it. That Interaction will deep link them into your app and create a re-engagement conversion in the system. Then, after a few minutes, they leave your app without purchasing the item.

Continuing the scenario, a few hours later the same customer sees another ad promoting a second discounted item in your app and decides to tap the ad.

This creates another re-engagement conversion in the system. After some time in the app, they decide to go back and purchase the first discounted item. Using conversion tags, you can update the conversion value for the original conversion corresponding to Discount 1. This will be really useful if you run re-engagement campaigns for multiple products in your app at the same time. To begin measuring overlapping conversion windows, set the EligibleForAdAttributionKitOverlappingConversions key to YES in the Info.plist for your app. Without this, prior conversions will continue to lock when they overlap, as they did before.

Next, I’ll show you how your app can get conversion tags.

Once your app has opted in, conversion tags will be appended to the re-engagement URL that AdAttributionKit delivers to your app when a re-engagement occurs.

Re-engagement URLs are Universal Links that are passed into APIs when either a custom rendered or StoreKit rendered ad is on the screen.

The tag is delivered as the value of AdAttributionKit’s re-engagement open parameter. In this example URL, the tag is equal to 1.

When your app receives a re-engagement URL, you can extract the conversion tag using a function like this. I'll break down what's happening here. First, the function gets the components of the URL that were passed in using URLComponents.

Next, it gets the list of query items. AdAttributionKit always appends a re-engagement open parameter if the app was open because of a re-engagement.

Next, it looks through the list of query parameters that are attached on the URL.

If it finds the reengagement open parameter on the URL, it’ll return the value of that parameter immediately. If it’s not able to find the query parameter, the function will return nil.

Now that you have a conversion tag in your app, you can use it to update that conversion directly.

We recommend associating conversion tags with the reengagement conversion that created it, so you can tie back meaningful events that occur as a result of that conversion.

You should also store the conversion tag either locally in your app or in a server-side data store.

Once a customer performs an action in your app that you’d like to measure for that specific conversion, retrieve the tag for that conversion.

Now, let me show you how to use a conversion tag to make a directed update to a conversion in code.

This function takes a conversion value in conversion tag to update a specific postback. When initializing a PostbackUpdate struct, pass in the conversion tag for the conversion you’d like to update.

Then you can call the Postback API to update the conversion value.

You can also call the updateConversionValue API without a conversion tag, and the system will update the most recent conversions postbacks.

And that’s how you can use conversion tags to update postbacks when you have overlapping conversion windows. Measuring conversion values for postbacks is only one piece of the puzzle when using AdAttributionKit. Interpreting postback data you receive downstream is another important aspect of the system, and can help inform marketing decisions you might make for your app's business. Yuchi, do you have updates to share in this space? I sure do. Here are some new features that will help you better consume and interpret the postback data you receive. To capture the most meaningful signals in your postback data, we added the ability to customize the attribution rules for your app, which enables you to adjust your attribution flow.

There are two ways in which you could adjust your attribution flow.

The first one is configurable attribution window.

Revisiting the end-to-end ad attribution flow, AdAttributionKit performs attribution based on ad recency and ad type.

The two ad types supported by AdAttributionKit are click-through ad and view-through ad.

Different ad types typically target a different time horizon. For example, a click-through ad might target driving conversions within 10 days. And when a conversion happens later than the targeted time frame, let’s say at 20 days after the impression display time, this conversion should no longer be considered driven by this ad. And this ad targeting time frame is what we refer to as the attribution window.

The attribution window is defined as the time period starting from the ad display time for the latest time that this ad can still be considered for attribution.

If conversion happens within the attribution window of an ad, then this ad would compete for the attribution of this conversion. Otherwise, this ad would not compete for the attribution of this conversion. Previously, all click-through ads that are less than 30 days old, and view-through ads that are less than 1 day old would be considered for attribution. We wanted to make this period flexible for you, and therefore, we’re introducing configurable attribution window.

As an advertiser, you can specify your desired attribution window length in the Info.plist file. This example uses a JSON file to illustrate the configurations, but the same keys and structure can be used when editing your app’s Info.plist file. Attribution window can be defined on a per-ad network basis and a per-ad interaction type basis that are view-through ads and click-through ads.

Here's an example. For the ad network com.example.adNetwork, the advertiser specified an attribution window of two days for click-through ads and one day for view-through ads. If an ad network partner focuses primarily on one type of ad, you might want to completely ignore other ad types from that ad network. You can do this by specifying the ignoreInteractionType key. This key can be set together “view” or “click”, but not both simultaneously. If you work with multiple ad networks, specifying attribution window length for them one by one can be a lot of work. In this case, you can specify a window length for all ad networks you work with by adding the global key, which is applied to all ad networks by default. On top of the global window length, you can also configure the attribution window length for specific ad networks, which will take precedence over the global configuration.

If no ad network or global configuration is found, we will fallback to the default attribution window length we use today. In the example, the attribution window for click-through ads from ad com.example.adNetwork will be five days, and view-through ads from that ad network will be ignored. For all other ad networks, the attribution window for view-through ads will be three days. Note that the concept of attribution window only applies to install ads, not re-engagement ads. This is because re-engagement ad interactions and conversions happen right after each other with no time gap in between.

The second way in which you can adjust your attribution flow is the configurable cooldown.

Revisiting the end-to-end ad attribution flow. Let’s focus on the user engagement measurement following an ad-driven conversion. After an ad network serves an ad, and the ad-driven conversion happens, the window for advertisers to measure user engagement opens. We refer to this window as the conversion window. Advertisers can measure the value of the conversion based on activities people take in their app, such as subscription and In-App Purchase, by invoking the updateConversionValue API.

In reality, many of these ad attributions might be happening simultaneously for the same advertised app on the same device. And the conversion windows may overlap, in which case, a measurement might not get accorded to the most appropriate conversion.

Let’s walk through a more concrete example.

If someone clicked on an ad and downloaded the advertised app, and a bit later performed an In-App Purchase, which resulted in a high user value measurement towards the install ad.

But imagine immediately after installing the app, the same person tapped on a re-engagement ad and opened the app. Then the In-App Purchase that should have been attributed to the install ad would be attributed to the re-engagement ad. This might not be the desired measurement objective for you.

The same scenario may occur for a re-engagement ad that closely follows another re-engagement conversion. What would have been attributed to the first re-engagement ad, will not get attributed to the second re-engagement ad. To prevent this, you might want to set a period after each conversion to block other signal and use that period only to measure value of ads that drove the dedicated conversion. This is what we call the configurable attribution cooldown. The configurable attribution cooldown can be specified on a per conversion type basis. The cooldown will start from every conversion of that specific type, and all other conversions that happened before the cooldown fully elapsed will not be attributed towards any conversion. As an advertiser, you can specify your desired attribution cooldown in the Info.plist file. In this example, an advertiser specified a cooldown of six hours for install and one hour for re-engagement. With this configuration, let’s say someone clicked on the installation ad and then installed an app at time T. And the configured cooldown for install is six hours. If the same person tap on the re-engagement ad and opened the app four hours after the install, then this re-engagement conversion will not be attributed to the ad.

If let’s say the re-engagement ad tab and app open happened seven hours after the install, then the re-engagement will receive an ad attribution.

For both configurable attribution window and attribution cooldown, the JWS format will remain unchanged for the impressions and the postbacks. Aside from these configurable features, we’ve also added new geography information to postbacks that will help you measure the success of your ad campaigns in different countries.

Back to the end-to-end ad attribution flow. Now let's focus on postbacks.

Postbacks are the outputs of AdAttributionKit which transmit information about the conversion, such as attribution, and user engagement measurement. Postbacks are delivered to the ad networks and optionally to the developers of advertised apps. We understand that advertisers and ad networks would like to access the geo info for conversions in order to optimize ad delivery. Today, some implementations rely on the source identifier for this information. With the latest AdAttributionKit, the country code is provided as a new field in the postback. Here’s what country code represents in different context.

For apps installed from the App Store, country code in the postback is derived from the App Store storefront that the app was downloaded from based on the location selected in user’s Account Settings.

For re-engagement conversion, postbacks use the same location from when the app was initially installed.

With iOS 17.4, alternative app marketplaces can supply an install verification token to communicate an app installation signal with an Apple device. The install verification token is a JWS token with payload including information about the app install, such as the timestamp of the download, and the downloaded app ID. Starting with the new iOS version, alternative app marketplaces provide a new field for country code in the install verification token payload. Sign it, and send to Apple. Then Apple will validate the value and populate the postback country code field with the code.

The country code is an optional field in the install verification token. If the system cannot find a country code in the install verification token, then there will be no country code in the postback.

Note that the country code value for conversion via alternative app marketplaces is limited to the locations where alternative marketplaces are supported.

This is how country code will be added to the postback. Country code will be an unsigned field parallel to the ad-interaction-type, signed JWS token, and coarse-conversion-value. The country code field is subject to the crowd anonymity algorithm that AdAttributionKit enforces to all postbacks. Crowd anonymity algorithm sits at the center of our privacy preserving ad attribution, where we ensure each individual’s uniqueness blend into a big crowd before releasing identifiable information to the advertiser and ad network.

The postbacks will only contain country code if there has been enough volume for similar conversions within the same country. The crowd anonymity tier that qualifies for country code presence in the postback will be a bonus tier on top of the four crowd anonymity tiers we enforce today. This means that under no circumstance advertisers and ad networks will lose the data they’re currently receiving. That concludes our latest updates to postback data. Mike will now share our new AdAttributionKit testability. Thanks Yuchi for all that great information. Now that we covered all the new features of AdAttributionKit, I’ll show the new ways to test your implementation.

Let’s return to our end-to-end diagram and focus on the ad delivery and conversion flow.

This is a typical flow you might use when testing your app’s AdAttributionKit implementation.

First, you need to create and serve an ad payload for your advertised app.

Then you display and interact with an ad in a separate publisher app, and then perform an install or re-engagement conversion to create development postbacks for your app.

With iOS 18.4, you can now create development postbacks for your app directly in the iOS Settings app.

Postbacks created from developer settings allow you to test in new ways. You can now test updating conversion values if your app was run from Xcode or other distribution mechanisms, such as ad-hoc distribution. You also now have direct control over the data your postbacks will contain. This can be useful for testing your server implementation for processing various data tiers of postbacks.

Now I’ll show how you can use developer settings to create postbacks for your app.

Before you start, you'll need to make sure Developer Mode is enabled on your device. Next, go into the developer settings inside of the Settings app.

Inside of developer settings, scroll down to the Ad Attribution Testing section.

We added a new page named Development Postbacks above AdAttributionKit Developer Mode.

Tapping into the Development Postbacks page, you’re presented with options to configure postbacks for your app, transmit any eligible postbacks, or clear all development postbacs from your device.

To configure development postbacks, type in your app’s bundle identifier and tap the Configure button.

The app must be installed on your device before you can create postbacks for it.

The first step is to specify a destination for your postback. This should be the URL of your server.

It is best practice to use a development URL when testing, different than the URL where you receive production postbacks.

You can also fetch the postback copy URL from your app automatically. You can use this to confirm the well-known URL that the system generates matches the URL your server exposes.

Next, fill in the properties of your postback. You can configure the postback to represent any type of conversion you would like by editing the properties.

Now in iOS, you’ll be able to configure country code as a new property. This will help you test country code in postbacks, which Yuchi discussed earlier.

After configuring the properties, you can adjust the data granularity of each individual postback.

This granularity controls how much information will be sent to your server. You can use this to validate your server implementation processes different postback data tiers correctly.

When you’re done configuring your postbacks, tap the button to create them for your app.

Now that your app has development postbacks, you can start updating their conversion values.

During testing, call the updateConversionValue(_:) API to update the development postbacks.

You can wait for the development postback to send automatically, or you can tap the Transmit Development Postbacks button when your postback conversion window ends.

Postbacks created in developer settings have some key differences than ones created in end-to-end flows. I’ll show the changes you’ll see in your postback’s JSON Web Signature.

This is a snippet of the header you would receive in your postback.

Postbacks created from developer settings are signed using a new key, indicated with a new kid value. Check out our documentation on verifying postbacks to obtain the new public key to validate the signature of these postbacks.

Switching focus, the payload of the postback also has some differences that are worth mentioning.

The ad network identifier will always be set to development.adattributionkit. This helps further distinguish postbacks created in developer settings from production postbacks.

The advertised item identifier of the postback may also be zero. For example, if you ran your app from Xcode while testing.

And that wraps up the new testability features we’ve added to AdAttributionKit. We think this new testability will help streamline your workflow when developing and testing your AdAttributionKit implementation. We covered a lot of ground today for our new AdAttributionKit features. From measuring overlapping conversion windows in your app to receiving country code and postbacks, these updates impact various pieces of ad attribution.

Some next steps: if you’re ready to configure attribution rules for your app, be sure to start adding the new configuration keys to your app’s Info.plist. Start using the new testability to test out your AdAttributionKit implementation earlier in your development lifecycle, before releasing to production. And if you’re using SKAdNetwork, now is a great time to migrate over to AdAttributionKit and start building with all of the new features. We want to thank our community of developers that give us feedback on their experiences using our privacy-first ad frameworks. Your feedback helps drive what we build and how we can deliver excellent ad experiences for your app that maintain user privacy. Thank you!