Why should I install the UA SDK?
The consumer privacy changes released in iOS 14 will make it more complex to scale User Acquisition (UA) campaigns moving forward.
Unity’s UA SDK, built on top of the deltaDNA SDK, allows you to continue to optimize your User Acquisition campaigns in a privacy-centric manner, while supporting Apple’s ATT privacy framework and SKAD integration.
This guide assumes that you have already installed and setup the deltaDNA SDK for either Unity or iOS. For details on how to do this, see the deltaDNA SDK documentation for reference:
iOS: https://docs.deltadna.com/advanced-integration/ios-sdk/
Unity: https://docs.deltadna.com/advanced-integration/unity-sdk/
Note that the Pinpointer methods, designed for iOS 14, will only send events in iOS 12+. If used on another iOS version (or on another platform in the case of the Unity SDK) they will do nothing.
By integrating, accessing, or using the deltaDNA UA SDK, you acknowledge and agree that (1) your access to and use of the deltaDNA UA SDK is governed by Unity’s Monetization Terms of Service, available here, and that such service is an Experimental Service (as defined therein); and (2) you will not access or use the deltaDNA UA SDK in connection with any application that is “directed to children” under the age of 13 or would otherwise be subject to the Children’s Online Privacy Protection Act of 1998, or with any application designated as a “Kids” or “Family” application in the Apple App Store or Google Play Store.
Setting up the UA SDK
Once you have set up and configured the deltaDNA SDK following the above documentation, register the Apple Store ID and Apple Developer ID for your game in the UA SDK.
The best place to do this is just after you start the deltaDNA SDK. The code snippets below show the properties you need to set.
Unity SDK
|
1 2 |
DDNA.Instance.AppStoreID = "1234567890"; |
iOS SDK (Objective-C)
|
1 2 |
[DDNASDK sharedInstance].appStoreId = @"1234567890"; |
iOS SDK (Swift)
|
1 2 |
DDNASDK.sharedInstance()?.appStoreId = @"1234567890" |
You will also need to import the required events into your deltaDNA project on the web portal. To do this:
- Navigate to the Setup > Manage Events screen
- Click Create Event
- Choose the unitySignalInstall event from the template event dropdown menu
- Click Import
- Scroll down and click Save
- Repeat for the unitySignalPurchase and unitySignalSession events
Using the UA SDK
There are 3 helper methods provided by the SDK to send the pinpointer events required:
unitySignallInstall, unitySignalSession, and unitySignalPurchase.
unitySignalInstall
This event should only be sent on the first startup of the game. To send the unitySignalInstall event, add the following code snippets to the startup code of the game.
Unity SDK
|
1 |
DeltaDNA.AudiencePinpointer.RecordInstallEvent(); |
iOS SDK (Objective-C)
|
1 |
[[DDNASDK sharedInstance] recordSignalTrackingInstallEvent]; |
iOS SDK (Swift)
|
1 |
DDNASDK.sharedInstance()?.recordSignalTrackingInstallEvent() |
The unitySignalInstall event contains the following data:
- connectionType: Whether the device is connected to WiFi, cellular, or otherwise
- sdkVersion: The version of the UA SDK that sent the event
- appStoreID: The iTunes Connect ID for the game
- appBundleID: The bundle ID for the application
- appDeveloperID: The Apple developer ID for the game developer
- idfv: The IDFV for the user’s device
- idfa: The IDFA for the user, if the user has granted permission to use it
- attTrackingStatus: The IDFA tracking authorisation status from iOS 14
- deviceName: The model of the user’s device as reported by iOS
- userCountry: The region code from the user’s device
- limitedAdTracking: Is there an IDFA present? (true if the IDFA is missing)
unitySignalSession
This event should be sent every time the user starts a new game session. The following code samples show how to use this event.
Unity SDK
|
1 |
DeltaDNA.AudiencePinpointer.RecordSessionEvent(); |
iOS SDK (Objective-C)
|
1 |
[[DDNASDK sharedInstance] recordSignalTrackingSessionEvent]; |
iOS SDK (Swift)
|
1 |
DDNASDK.sharedInstance()?.recordSignalTrackingSessionEvent() |
The unitySignalSession event contains the following data:
- connectionType: Whether the device is connected to WiFi, cellular, or otherwise
- sdkVersion: The version of the UA SDK that sent the event
- appStoreID: The iTunes Connect ID for the game
- appBundleID: The bundle ID for the application
- appDeveloperID: The Apple developer ID for the game developer
- idfv: The IDFV for the user’s device
- idfa: The IDFA for the user, if the user has granted permission to use it
- attTrackingStatus: The IDFA tracking authorisation status from iOS 14
- deviceName: The model of the user’s device as reported by iOS
- userCountry: The region code from the user’s device
- limitedAdTracking: Is there an IDFA present? (true if the IDFA is missing)
unitySignalPurchase
This event should be sent every time the user makes a transaction or purchase within the application. It requires a currency amount (as an integer), a currency type (as a string, e.g. GBP for UK pounds, or USD for US dollars). It also requires the transaction ID and transaction receipt data (in the default base64 string) from the StoreKit API, in order to validate the transaction is genuine, as mentioned below
The currency amount should be in the smallest denomination of the relevant currency, for example if the currency is USD the amount should be in cents. There are helper methods available in the SDKs to make this conversion easier, as shown below.
Purchase Verification
In order to verify that the transactions recorded in the purchase events are genuine, a second event (“transaction”) is sent alongside the unitySignalPurchase event, containing the transaction receipt data and transaction ID. If you wish to use deltaDNA’s other features, and you want to manually record transaction events in order to capture additional transaction data, you can set the setting AutomaticallyGenerateTransactionForAudiencePinpointer to false, which will disable the auto-send behavior. Please note that if you do this and do not send a transaction event with a matching transaction ID, your purchases will not be verified.
Unity SDK
|
1 2 |
int currencyAmount = Product.ConvertCurrency("USD", (decimal) 12.34); DeltaDNA.AudiencePinpointer.RecordPurchaseEvent(currencyAmount, "USD", "transactionID", "transactionReceiptData"); |
iOS SDK (Objective-C)
|
1 2 3 |
NSDecimalNumber *decimalCurrency = [NSDecimalNumber decimalNumberWithDecimal:[@123.23 decimalValue]]; NSInteger currencyAmount = [DDNAProduct convertCurrencyCode:@"GBP" value:decimalCurrency]; [[DDNASDK sharedInstance] recordSignalTrackingPurchaseEventWithRealCurrencyAmount :@(currencyAmount) realCurrencyType:@"GBP" transactionID:@"transactionID" transactionReceipt:@"transactionReceiptData"]; |
iOS SDK (Swift)
|
1 2 |
let currencyValue = DDNAProduct.convertCurrencyCode("GBP", value: NSDecimalNumber(decimal: 123.23)) DDNASDK.sharedInstance()?.recordSignalTrackingPurchaseEvent(realCurrencyAmount: NSNumber(value: currencyValue), realCurrencyType: "GBP", transactionID: "transactionID", transactionReceipt: "transactionReceiptData") |
Data Included
The unitySignalPurchase event contains the following data:
- connectionType: Whether the device is connected to WiFi, cellular, or otherwise
- sdkVersion: The version of the UA SDK that sent the event
- appStoreID: The iTunes Connect ID for the game
- appBundleID: The bundle ID for the application
- appDeveloperID: The Apple developer ID for the game developer
- idfv: The IDFV for the user’s device
- idfa: The IDFA for the user, if the user has granted permission to use it
- attTrackingStatus: The IDFA tracking authorisation status from iOS 14
- deviceName: The model of the user’s device as reported by iOS
- userCountry: The region code from the user’s device
- limitedAdTracking: Is there an IDFA present? (true if the IDFA is missing)
- realCurrencyAmount: The amount the user spent in the purchase, in the smallest denomination of the relevant currency
- realCurrencyType: The currency code which the user spent in the purchase (e.g. GBP for British Pounds).
- transactionID: The StoreKit ID for the in app purchase
Additionally, the accompanying transaction event contains the following data:
- transactionReceipt: The base64 encoded receipt data from StoreKit, used for transaction verification
