• Platforms
  • Partners
  • Forums
  • 日本語
  • TLC Tealium Learning Center Tealium Learning
    Community
  • Discussions & Ideas Dicussions & Ideas
  • Product Guides Product Guides
  • Knowledge Base Knowledge Base
  • Developer Docs Developer Docs
  • Education Education
  • TLC Blog TLC Blog
  • Support Desk Support Desk
  • CDH Customer Data Hub Customer Data Hub
  • Mobile
  • Getting Started
    • Overview
    • Quick Start Guide
    • Mobile Concepts
    • Client-Side
    • Server-Side
    • Tracking Webviews
    • Data Layer
    • Consent Management
    • Event Batching
    • User Location and Geofencing
    • Media Tracking
    • Deep Links
    • Timed Events
    • Trace
    • Hosted Data Layer
    • Adobe Visitor Service Module
    • Feature Comparison
    • Troubleshooting
  • Remote Commands
    • Overview
    • How It Works
    • Integrations
      • Adjust
      • AppsFlyer
      • Branch
      • Braze
      • Contentsquare
      • Facebook
      • Firebase
      • Kochava
      • Usabilla
  • Android (Java)
    • Overview
    • Install
    • Track
    • Data Layer
    • Data Management
    • Consent Management
    • Module List
      • Ad Identifier Module
      • Crash Reporter Module
      • Install Referrer Module
      • Lifecycle Tracking Module
      • Location Module
      • Optimizely X Tracking Module
    • Android TV
    • Android Wear
    • API Reference
      • ConsentManager
      • DataSources
      • Lifecycle
      • Tealium
      • Tealium.Config
      • TealiumLocation
    • Release Notes
  • Android (Kotlin)
    • Overview
    • Install
    • Track
    • Data Layer
    • Consent Management
    • Identity Resolution
    • Module List
      • Ad Identifier Module
      • AutoTracking Module
      • AdobeVisitorService Module
      • Collect Module
      • Collectors Module
      • Crash Reporter Module
      • In-App Purchase Module
      • Install Referrer Module
      • Lifecycle Tracking Module
      • Location Manager Module
      • Media Module
      • RemoteCommands Module
      • Tag Management Dispatcher Module
      • Visitor Service Module
    • Android TV
    • API Reference
      • ConsentCategory
      • ConsentManager
      • CurrentVisit
      • DataLayer
      • Lifecycle
      • LocationManager
      • Media
      • Tealium
      • TealiumConfig
      • VisitorProfile
      • VisitorService
    • Release Notes
  • Cordova 1.x
    • Overview
    • Install
    • Track
    • Data Management
    • Module List
      • Ad Identifier Module
      • Crash Reporter Module
      • Install Referrer Module
    • API Reference
    • Release Notes
  • Cordova 2.x
    • Overview
    • Install
    • Track
    • API Reference
    • Release Notes
  • Flutter 1.x
    • Overview
    • Install
    • Track
    • Consent Management
    • Data Management
    • API Reference
    • Release Notes
  • Flutter 2.x
    • Overview
    • Install
    • Track
    • Consent Management
    • Data Management
    • API Reference
      • Tealium
      • TealiumConfig
      • VisitorProfile
    • Release Notes
  • iOS (Objective-C)
    • Overview
    • Install
    • Track
    • Data Layer
    • Data Management
    • Consent Management
    • Tag Management
    • Module List
      • Lifecycle Tracking Module
    • tvOS
    • watchOS
    • API Reference
    • Release Notes
  • iOS (Swift) 1.x
    • Overview
    • Install
    • Track
    • Data Layer
    • Data Management
    • App Extensions
    • Identity Resolution
    • Consent Management
    • Modules
    • Module List
      • AppData Module
      • Attribution Module
      • AutoTracking Module
      • Collect Module
      • Connectivity Module
      • CrashReporter Module
      • DataSource Module
      • DefaultStorage Module
      • Delegate Module
      • DeviceData Module
      • DispatchQueue Module
      • FileStorage Module
      • Lifecycle Module
      • Location Module
      • Logger Module
      • PersistentData Module
      • RemoteCommands Module
      • TagManagement Module
      • VisitorService Module
      • VolatileData Module
    • Feature Comparison
    • Working with Objective-C
    • API Reference
      • TealiumConfig
      • TealiumConsentCategories
      • TealiumConsentManagerDelegate
      • TealiumConsentManager
      • TealiumInstanceManager
      • TealiumPersistentData
      • TealiumVolatileData
      • Tealium
    • Release Notes
  • iOS (Swift) 2.x
    • Overview
    • Install
    • Track
    • Data Layer
    • Consent Management
    • App Extensions
    • Identity Resolution
    • Modules
    • Module List
      • AppData Module
      • AdobeVisitorService Module
      • Attribution Module
      • AutoTracking Module
      • Collect Module
      • Connectivity Module
      • CrashReporter Module
      • DeviceData Module
      • In-App Purchase Module
      • Lifecycle Module
      • Location Module
      • Media Module
      • RemoteCommands Module
      • TagManagement Module
      • VisitorService Module
    • Working with Objective-C
    • API Reference
      • LocationModule
      • MediaSession
      • Tealium
      • TealiumConfig
      • TealiumConsentCategories
      • TealiumConsentManager
      • TealiumDataLayer
      • TealiumInstanceManager
    • Release Notes
  • NativeScript
    • Overview
    • Install
    • Track
    • API Reference
      • Tealium
      • TealiumConfig
    • Release Notes
  • React Native 1.x
    • Overview
    • Install
    • Track
    • API Reference
    • Release Notes
  • React Native 2.x
    • Overview
    • Install
    • Track
    • Location Module
    • API Reference
    • Release Notes
  • Unity 1.x
    • Overview
    • Install
    • Track
    • API Reference
  • Unity 2.x
    • Overview
    • Install
    • Track
    • API Reference
  • Xamarin 1.x
    • Overview
    • Install
    • Track
    • Data Management
    • Consent Management
    • API Reference
    • Release Notes
  • Xamarin 2.x
    • Overview
    • Install
    • Track
    • Data Layer
    • Consent Management
    • API Reference
    • Release Notes
  • Web
  • Getting Started
    • Overview
    • Quick Start Guide
    • Web Concepts
    • Data Layer
      • An Introduction to the Data Layer
      • How the Data Layer Works for Websites
      • Data Layer Best Practices
      • Definitions
        • Retail
        • Publisher
        • Hotel
        • Travel
        • Basic Video Tracking
  • Adobe Launch
    • Overview
    • Install
    • Data Layer
  • AMP
    • Overview
    • Install
    • Track
    • Data Layer
  • Angular
    • Overview
    • Install
    • Track
    • API Reference
  • Google Tag Manager
    • Overview
    • Install
    • Data Layer
  • JavaScript (Web)
    • Overview
    • Install
    • Track
    • Data Layer
    • Universal Data Object (utag_data)
    • Universal Tag (utag.js)
    • Data Layer Object (b)
    • Single-Page Applications
    • Settings
    • Debugging
    • API Reference
      • Cookie Functions
      • GDPR Functions
      • Tracking Functions
      • Utility Functions
    • Release Notes
  • Server
  • C#
    • Overview
    • Install
    • Track
    • Data Layer
    • API Reference
    • Release Notes
  • HTTP API
    • Overview
    • Endpoint
    • Data Layer
  • Java
    • Overview
    • Install
    • Track
    • API Reference
    • Release Notes
  • Node
    • Overview
    • Install
    • Track
    • API Reference
  • Python
    • Overview
    • Install
    • Track
    • API Reference
  • Roku
    • Overview
    • Install
    • Track
    • API Reference
  • Ruby
    • Overview
    • Install
    • Track
    • API Reference
IOS SWIFT/MODULE LIST

Attribution Module

Adds the user-resettable advertising identifier (IDFA) to each tracking call and, optionally, implements the Apple Search Ads API to gather attribution information.

Usage

The Attribution module adds the user-resettable advertising identifier (IDFA) to each tracking call and, optionally, implements the Apple Search Ads API to gather attribution information. Learn more about setting up Apple Search Ads attribution.

In version 2.1.1+, the attribution module also includes SKAdNetwork support and adds the ATTransparency.AuthorizationStatus to the dispatch payload.

Use of this module is optional. Take the time to read about its functionality and decide if you need it, as it introduces additional dependencies. You are required to explain to Apple why you are using IDFA when you submit your app. If you do not state that you are using IDFA, Apple rejects your app. Learn more about IDFA usage and rejections.

The following platforms are supported:

  • iOS

Requirements

  • UIKit
  • AdSupport
  • iAd
  • iOS 14+: AppTrackingTransparency
  • iOS 14+: StoreKit

Install

Install the Attribution module with Swift Package Manager, CocoaPods or Carthage.

Swift Package Manager (Recommended)

Supported in version 1.9.0+, the Swift Package Manager is the recommended and simplest way to install the Tealium Swift library:

  1. In your Xcode project, select File > Swift Packages > Add Package Dependency
  2. Enter the repository URL: https://github.com/tealium/tealium-swift
  3. Configure the version rules. Typically, "Up to next major" is recommended. If the current Tealium Swift library version does not appears in the list, then reset your Swift package cache.
  4. Select the Attribution module from the list of modules to install and add it each of your app targets in your Xcode project, under Frameworks > Libraries & Embedded Content

Learn more about the Swift Package Manager installation for iOS.

CocoaPods

To install the Attribution module with CocoaPods, add the following pod to your Podfile:

pod 'tealium-swift/Attribution'

Learn more about the CocoaPods installation for iOS.

Carthage

To install the Attribution module with Carthage, following these steps:

  1. Go to the app target’s General configuration page in Xcode.

  2. Add the following framework to the Embedded Binaries section:

    TealiumAttribution.framework
    

Learn more about the Carthage installation for iOS.

Initialize

To initialize the module include it in the collectors property.

config.collectors = [Collectors.Attribution]

Attribution in iOS 14+

In iOS 14+, apps are required to receive user permission to access the device’s advertising identifier (IDFA). The user is prompted to grant “Permission to track” when the app launches for the first time. If the user declines, then the IDFA is not available to the app.

When the IDFA is not available, SKAdNetwork provides a method for registered advertising networks to attribute app installs to a campaign by receiving a signed signal directly from Apple. The advertising network only receives confirmation that the app was successfully installed, along with the campaign ID and optional conversion value.

Learn more about the AppTrackingTransparency and SKAdNetwork frameworks in What Do Apple’s IDFA Changes Mean for Tealium?

AppTrackingTransparency (ATT)

With the attribution module enabled, the user’s tracking authorization status is automatically added to the dispatch payload as device_tracking_authorization and the value is a string representation of the ATTrackingManager.AuthorizationStatus enumeration.

If applicable, call ATTrackingManager.requestTrackingAuthorization separately. Learn more about requesting tracking authorization to enable the Tealium SDK.

SKAdNetwork

Tealium automatically calls SKAdNetwork.registerAppForAdNetworkAttribution() on launch if config.skAdAttributionEnabled is set to true. This permits advertising networks to anonymously validate app installs. If the config.skAdConversionKeys dictionary is defined, then SKAdNetwork.updateConversionValue() is automatically called on the specified event and sent the value of the specified conversion key.

config.skAdConversionKeys = ["EVENT_NAME": "DATA_LAYER_VARIABLE"]

The conversion value must be an Int with a value between 0 and 63. If the conversion value is a decimal, it must be converted to an integer before calling the conversion event.

Example:

config.skAdConversionKeys = ["purchase": "conversion_value"]
...
tealium?.track("purchase", dataLayer: ["order_subtotal": 456.87, "conversion_value": conversionValue])

Learn more about the SKAdNetwork framework.

Process

The following diagram shows the path of an ad’s install validation. App A is the source app that displays an ad, and App B is the advertised app that the user installs.

skad-custom.png

When a user clicks on an ad within an app or mobile web browser, the App Store is launched and the user is taken to the product screen for the ad campaign. In iOS 14.5+, advertisers have the option to choose to display a custom view-through ad or a StoreKit-rendered ad. If the user installs the advertised app, the device stores a pending install validation. If the user opens the app within an attribution time window, the device sends the install validation postback to the ad network.

The notification is signed by Apple and includes the campaign ID, but excludes user or device-specific data. The postback may include a conversion value and the source app’s ID if Apple determines that providing the values meets Apple’s privacy threshold.

Learn more about advertisement-driven app installations.

Tealium’s Role

There are three main parties involved in Apple’s SKAdNetwork solution:

  1. Ad networks
  2. Source app
  3. Advertised apps

Tealium wraps the calls to SKAdNetwork. If the TealiumAttribution module and the configuration flag are enabled, then SKAdNetwork.registerAppForAdNetworkAttribution() is called on app launch.

Additionally, if you have defined the skAdConversionKeys, then the SKAdNetwork.updateConversionValue(_:) method is called and passed in the specified conversion value. Tealium permits you to manage your calls to SKAdNetwork through the tracking you already have in place.

You may need to request tracking authorization from your users and add the appropriate keys to your .plist file.

The following diagram shows shows how Tealium works with SKAdNetwork:

skad-tealium-custom.png

Validation

Learn about validating the calls to SKAdNetwork.

Search Ads API

To use Apple Search Ads API, enable the searchAdsEnabled property of the TealiumConfig object. Then use the iAd framework to retrieve the attribution dictionary which contains the attribution object. The Tealium library does this as soon as the app launches, but it is possible that the information is not retrieved in a timely manner. The information is added to the data layer after receiving it from Apple, typically during the launch event.

In some cases there may be several events after launch. These variables are only retrieved from Apple’s servers once during the app’s lifetime, and are stored as persistent variables so that they become available on future app launches.

Data Layer

The following variables are transmitted with each tracking call while the module is enabled:

Variables prefixed with ad_ are only set if Search Ads has been enabled.

Variable Name Description Example
ad_campaign_id The corresponding ad’s campaign ID 1234567890
ad_campaign_name The corresponding ad’s campaign name CampaignName
ad_creativeset_id The ID of the Creative Set which the corresponding advertisement was part of. 456093
ad_creativeset_name The name of the Creative Set which the corresponding advertisement was part of. Beast Images
ad_group_id The corresponding ad’s campaign group ID 1234567890
ad_group_name The corresponding ad’s campaign group name AdGroupName
ad_keyword The keyword that drove the advertisement impression which led to the corresponding click Keyword
ad_keyword_matchtype This may either be Broad, Exact or Search Match. Exact
ad_org_id The corresponding ad’s campaign organization ID OrgID
ad_org_name The corresponding ad’s campaign organization name OrgName
ad_purchase_date Date and time the user first downloaded your app. In the case where iadconversion-type = “Redownload”, this represents the original purchase date. This may or may not have been associated with an Apple Search Ad. 2016-12-05T17:31:40Z
ad_region Identifies the country or region associated with the campaign which drove this install. US
ad_user_clicked_last_30_days Boolean indicating if user clicked on a Search Ads impression within 30 days prior to app download true
ad_user_conversion_type Identifies new download or re-download of the app Download
ad_user_date_clicked Date and time the user clicked on a corresponding ad 2016-12-05T17:31:40Z
ad_user_date_ converted Date and time the user downloaded the app 2016-12-05T17:31:40Z
device_tracking_authorization iOS 14+ only. ATTrackingManager.AuthorizationStatus [notDetermined, restricted, denied, authorized]
device_advertising_enabled Boolean indicating if the user allowed advertisement tracking (if false, the advertising ID appears as a string of 0’s) true
device_advertising_id User-resettable advertising identifier (IDFA) 6D92078A-8246...
device_advertising_vendor_id Unique ID guaranteed to be the same across all apps on the same device from a single vendor (apps with the same 1st 2 parts of the RDNS bundle identifier. For example, com.tealium or com.acme) 6D92078A-8246...
"AdobeVisitorService Module "
Previous
AdobeVisitorService Module
Next
AutoTracking Module
"AutoTracking Module"

 

Was this article helpful?

This page was last updated: May 12, 2021      

Thank you for your feedback!

Table of Contents

  • Usage
  • Requirements
  • Install
    • Swift Package Manager (Recommended)
    • CocoaPods
    • Carthage
  • Initialize
  • Attribution in iOS 14+
    • AppTrackingTransparency (ATT)
    • SKAdNetwork
  • Search Ads API
  • Data Layer
  • Platforms
  • Partners
  • Forums
  • Mobile
  • Getting Started
  • Remote Commands
  • Android (Java)
  • Android (Kotlin)
  • Cordova 1.x
  • Cordova 2.x
  • Flutter 1.x
  • Flutter 2.x
  • iOS (Objective-C)
  • iOS (Swift) 1.x
  • iOS (Swift) 2.x
  • NativeScript
  • React Native 1.x
  • React Native 2.x
  • Unity 1.x
  • Unity 2.x
  • Xamarin 1.x
  • Xamarin 2.x
  • Web
  • Getting Started
  • Adobe Launch
  • AMP
  • Angular
  • Google Tag Manager
  • JavaScript (Web)
  • Server
  • C#
  • HTTP API
  • Java
  • Node
  • Python
  • Roku
  • Ruby