Oracle CX Advertising iOS SDK
Integrating the Oracle CX Advertising SDK (formally known as the Oracle Data Cloud platform) into your native and hybrid apps enables you to extract mobile user attributes from your screens (product page visits, purchase intent signals, add-to-cart actions, and conversions), and transfer them into the Oracle CX Advertising platform.
To import your mobile app data into the Oracle CX Advertising platform, add the Oracle CX Advertising SDK to the screens in your mobile app, pass phints (key-value pairs representing user attributes) to the platform, and create rules to map the phints into categories in your taxonomy.
Important!
- If you have not done so already, you need to inform Apple when you upload your app for review that you are using IDFA to serve advertisements.
- If a user has enabled Limit Ad Tracking in their settings, their data cannot be sent to Oracle CX Advertising servers.
-
For iOS version 14 onwards, if you are using any other consent management platform like GDPR along with the Oracle CX Advertising iOS SDK, make sure the consent pop-up is shown before the App Tracking Transparency (ATT) pop-up shown by the SDK. And the ATT pop-up should only be displayed, if the user provides consent to the other consent management pop-up (as per Apple guidelines).
Choosing the iOS SDK version
Choose the version of the Oracle CX Advertising iOS SDK you want to work with:
SDK version |
Features |
Next Steps |
---|---|---|
3.1.2 |
Extracting attributes for product page visits, purchase intent signals, add-to-cart actions, and conversions. |
Go to iOS SDK version 3.1.2 |
4.0.0 |
This is the latest version of the iOS SDK. Features include
To learn more, see the changelog. Important: If you are using TCFV2 integration (GDPR), initialize theOracle CX Advertising SDK once you accept or deny GDPR pop-up. Oracle CX Advertising SDK will read the GDPR consent from the device and will internally append GDPR consents in the URL accordingly. Learn more about integrating GDPR. |
Go to Steps to integrate the iOS SDK in your apps.
|
Steps to integrate the iOS SDK in your apps
To integrate the iOS SDK in your apps:
Step 1: Getting a site ID
To instantiate the Oracle CX Advertising platform SDK in your mobile app, you need a site ID. The site ID is used to manage your data in the Oracle CX Advertising platform. Classification rules use the site ID to identify into which categories to map user attributes. You generate a site ID by creating a container. You can create containers in the UI or with the containers API. It is a good practice to create separate site IDs for testing and for production environments.
After you create the container, open a Oracle Support ticket requesting "Direct Ingest Access for ADID" and include your partner name, partner ID, and the site ID.
Step 2: Scoping data
Identify the user attributes you want to extract from your mobile app and transfer to the Oracle CX Advertising platform. For example, if your app includes a screen about toasters, you could pass a toaster attribute to the platform when users visit that screen. If you purchased consulting services, your solutions consultant can work with you on scoping your mobile app and designing a data collection strategy.
Step 3: Integrating the SDK
To begin collecting page-level and user data from your mobile apps and transferring it into the Oracle CX Advertising platform, you need to install and implement the Oracle CX Advertising SDK. After you implement the SDK, you must re-release your app via the app store.
This section uses the Xcode environment as an example. You should appropriate adaptions if you use a different IDE.
Note: This topic discusses working with latest version of the Oracle CX Advertising iOS SDK. To work with version 2.1.9, see iOS SDK version 3.1.2.
Hashed email and unique customer ID ingestion
To ingest hashed emails or unique customer ID from SDK, open a Oracle Support ticket requesting "Enable hashed email delivery/unique customer ID delivery from SDK for particular site (site ID)" and include your partner name, partner ID, and the site ID.
Upgrading to the iOS SDK 4.0.0
If you previously used an older version of the Oracle CX Advertising iOS SDK, before installing the latest SDK, perform the following steps:
- Delete the libBluekai.a and Bluekai.h files manually from the project.
- Remove the references of above files under build settings / build phases etc.
- Remove the below import from all the files:
#import "Bluekai.h"
-
Continue to the steps outlined in Installing iOS SDK version 4.0.0.
Installing iOS SDK version 4.0.0
For first time users or users upgrading to latest version, follow the steps below to install the latest Oracle CX Mobile SDK and Oracle CX Advertising iOS SDK. After downloading the SDKs, you will import them into your Xcode project.
The following steps are relevant as of Xcode version 12.
-
Download the latest Oracle CX Mobile SDK and the Oracle CX Advertising iOS SDK.
-
Open your app or module under Xcode.
-
Tap on the project in the Project Navigator.
-
Select Target.
-
Select General Tab.
-
Navigate to Frameworks, Libraries, and Embedded Content section.
-
Add new framework by selecting + icon and then click Add Other > Add Files.
-
Select OracleCXMobileSDK.xcframework and OracleCXAdvertising.xcframework from your downloaded location.
After the above steps, verify the frameworks under Embedded Content section appear as illustrated below:
iOS 14+ ATT Support
After adding Oracle CX Advertising iOS SDK to your app, if you want to be able to send data to back end server in iOS14+ versions, it is important to prompt the end user informing that the data is being collected by your application for personalized advertising. The prompt text has to be compulsorily provided as value for NSUserTrackingUsageDescription
key in Info.plist.
<string>${PRODUCT_NAME} collects data for personalized advertising.</string>
Alternatively, you can view Info.plist as a property list, and follow the below steps:
-
Click "+" utton under Custom iOS Target Properties list present in the Info tab (Targets).
-
Type "Privacy - Tracking" in the search box.
-
Select "Privacy - Tracking Usage Description" in the search box.
-
Select the value box for the above key and provide the description text.
Setup the iOS SDK
There are two ways we can set up the Oracle CX Advertising iOS SDK.
-
Setting up the SDK with oracle.json - This is a recommended way to set up the SDK.
Setting up the SDK with oracle.json
This is a recommended way to set up the SDK. oracle.json is a single configuration file for all different CX modules. The sample oracle.json file can be found here. Place the oracle.json file in the main project folder and update the file with your own values. More details about oracle.json can be found in Oracle CX Mobile SDK documentation. Below are the steps to configure the SDK in Swift and Objective C.
Swift 5.1
import OracleCXAdvertising class ViewController: UIViewController, BlueKaiOnDataPostedListener { let blueKaiObj = BlueKai() let container = ORAAdvDataContainer() override func viewDidLoad() { super.viewDidLoad() container.loadFromConfigFile() blueKaiObj.delegate = self } }
Objective C
#import <OracleCXAdvertising/OracleCXAdvertising.h> @interface ViewController : UIViewController @property (nonatomic, strong) BlueKai *bluekai; @property (nonatomic, strong) ORAAdvDataContainer *container; @end @implementation ViewController - (void)viewDidLoad { [super viewDidLoad]; self.bluekai = [[BlueKai alloc] init]; self.container = [[ORAAdvDataContainer alloc] init]; [self.container loadFromConfigFile]; self.bluekai.delegate = (id)self; } @end
Setting up the SDK without oracle.json
Using the oracle.json file is recommended but optional. You can use the SDK without adding the oracle.json file to the project. This is not the recommended way, and the initialization method is deprecated. Below is the example code to set configurations.
Swift 5.1
import OracleCXAdvertising class ViewController: UIViewController, BlueKaiOnDataPostedListener { var blueKaiObj : BlueKai! override func viewDidLoad() { super.viewDidLoad() self.blueKaiObj = BlueKai.init(sideId: "2", appVersion: "1.2", devMode: false) self.blueKaiObj.delegate = self } }
Objective C
#import <OracleCXAdvertising/OracleCXAdvertising.h> @interface ViewController : UIViewController @property (nonatomic, strong) BlueKai *bluekai; @end @implementation ViewController - (void)viewDidLoad { [super viewDidLoad]; self.bluekai = [[BlueKai alloc] initDirectAutoIdfaEnabledWithSiteId:@"2" withAppVers]; self.bluekai.delegate = (id)self; } @end
Updating the Oracle CX Advertising SDK in future releases
Updating Oracle CX Advertising SDK to newer versions from current Oracle CX Advertising SDK version, can be done by just copying over the previous version, unless otherwise indicated.
Change Log
Implementing BlueKaiOnDataPostedListener
Declare the BlueKai SDK delegate in application. This step is optional and is required only if you need a callback when data is posted to DMP server.
@objc public protocol BlueKaiOnDataPostedListener
-
onDataPosted(status
-
onDataPosted(response:dataPosted:campaigns
Step 4: Classifying data
After you have integrated the iOS SDK into your app, you must write classification rules to map the page and user attributes you are extracting from your mobile app to categories in the Oracle Data Cloud platform. (A category is a collection of users that have the same attribute.)
Use the the Taxonomy Manager in the Oracle Data Cloud platform to create a data map, categories, and rules that will organize your mobile data into a taxonomy. Your data map must include the following information:
- The set of keys used in your phints
- The possible set of values for each key, and associate them with human readable category names, if necessary
- The hierarchical relationships, if any, between a set of keys
For example, consider an auto shopping site (myAutos.com) that collects the makes and models of cars for which users have demonstrated intent to purchase. The key-value pair for the make node would have the following syntax: MA100=value
. The example key-value pairs for this node could be as follows:
- MA100=Honda
- MA100=Acura
- MA100=Toyota
The key-value pair for the model node would have the following syntax: MA110=value
. Based on the previous example make nodes, example key-value pairs for the model node could be as follows:
- MA110=Accord
- MA110=Civic
- MA110=TL
- MA110=TSX
- MA110=Corolla
- MA110=Camry
If the values for the makes were encoded (for example, you pass 23098, 21409, 57983 instead of Honda, Acura, and Toyota), the platform would need human readable category names for these encoded values. For example, the following translations could be used:
- MA100=23098 > Honda
- MA100=21409 > Acura
- MA100=57983 > Toyota
The following data map could then be created for this site:
Key | Key translation | Value | Value translation (category name) |
---|---|---|---|
MA100 | Make | Honda | Honda |
MA100 | Make | 21409 | Acura |
MA100 | Make | 57983 | Toyota |
MA110 | Make > Model | Accord | Honda > Accord |
MA110 | Make > Model | 89065 | Honda > Civic |
MA110 | Make > Model | TL | Acura > TL |
MA110 | Make > Model | TSX | Acura > TSX |
MA110 | Make > Model | Corolla | Toyota > Corolla |
MA110 | Make > Model | Camry | Toyota > Camry |
Monitoring data ingest
After your app begins transferring data into the Oracle CX Advertising platform, you should verify that your data is being collected and classified correctly and that your app is generating the expected amount of inventory.
To monitor your data ingest:
- Check if your mobile app is calling the platform. Use the site hits report in the platform to verify that your app is sending calls.
- Check if your inventory is growing. Use the inventory trend report to verify that the amount of inventory per category is increasing daily.
- Check your 30-day inventory. Use the Audience Builder in the Oracle Data Cloud platform to view the estimated number of unique users in your categories based on current configurations.
You can also use the categories API to programmatically check your inventory of your unique users.