iOS SDK version 3.1.2

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.

Note: This topic discusses working with the iOS SDK version 3.1.2. To use the latest version of the SDK, see Oracle CX Advertising iOS SDK and review the changelog.

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 Data Cloud servers.

Downloading the SDK

To download the SDK:

Download iOS SDK version 3.1.2 and save the file.
Extract the SDK files from the archive.

Getting a site ID

To instantiate the Oracle Data Cloud platform iOS SDK in your mobile app, you need a site ID. The site ID is used to manage your data in the Oracle Data Cloud 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 MOS ticket requesting "Direct Ingest Access for ADID" and include your partner name, partner ID, and the site ID.

To onboard data for user profiles located in the European Union (EU), you must have signed Oracle's General Data Protection Regulation (GDPR) Consent agreement. If you have not signed the agreement, you can only create containers that are configured for non-EU countries. This means that a blacklist must include the EU region or countries and a whitelist may not. If you attempt to create a container with an invalid configuration, the UI or API displays an error. By default, new containers blacklist the EU. Contact your Oracle Account Representative to obtain and sign the GDPR Consent agreement.

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.

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.

Note: This topic discusses working with the iOS SDK version 3.1.2. To use the latest version of the SDK, see Oracle CX Advertising iOS SDK and review the changelog.

This section uses the XCode environment as an example. You should appropriate adaptions if you use a different IDE.

Adding the SDK to your project

In XCode, drag the BlueKai_SDK Library folder into the project directory.
In the dialog box that appears, choose the option that fits your environment.

Adding frameworks

You must add the AdSupport and SystemConfiguration frameworks to your project.

To add frameworks:

In XCode, go to your project properties
Select Build Phases.
Open the Link Binary With Libraries area and click the plus sign icon.
Type AdSupp in the search box.
Select AdSupport.framework from the list
Click Add.
Click the plus sign icon again and enter System in the search box.
Select SystemConfiguration.framework from the list.
Click Add.

Including the SDK

In the ViewController.h file or the header file of your view, add:

```objective-c
@class BlueKai;
```

At the top of the corresponding implementation (.m) file, add:

```objective-c
#import "BlueKai.h"
```

In the ViewController.h file, define an instance of the SDK:

```objective-c
@interface ViewController : UIViewController
{
    BlueKai *blueKaiSdk;
}
```

Initializing the SDK

You use the NSURLConnection initializer to establish a direct connection to the Oracle Data Cloud platform. There are two methods you can use in your implementation code. The initDirectAutoIdfaEnabledWithSiteId method automatically sends the IDFA:


```objective-c
blueKaiSDK = [[BlueKai alloc] initDirectAutoIdfaEnabledWithSiteId:@"2" withAppVersion:@"1.0" withDevMode:YES];
```

The initDirectWithSiteId method does not automatically send the IDFA, but can include the withIdfa:idfa parameter to send it:

		
```objective-c
blueKaiSDK = [[BlueKai alloc] initDirectWithSiteId:@"2" withAppVersion:version withIdfa:idfa withDevMode:YES];
```

For both methods, the app can get the IDFA by calling:

```objective-c
- (NSString *)identifierForAdvertising
{
    if([[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled])
    {
        NSUUID *IDFA = [[ASIdentifierManager sharedManager] advertisingIdentifier];
        return [IDFA UUIDString];
    }

    return nil;
}
```

You must also the opt-in preference to YES.

```objective-c
[blueKaiSDK setOptInPreference:YES];
```

To stop sending data to the Oracle Data Cloud platform, change the setting to NO:

```objective-c
[blueKaiSDK setOptInPreference:NO];
```

Send secure requests

You should always send requests by using HTTPS. To enable HTTPS for requests sent by your app, set [blueKaiSDK setUseHttps:YES]; in your ViewController.h file or implementation file. If necessary, you can add exceptions to your Info.plist file.

Important! You should not add exceptions unless there is no way to avoid it. Secure connections are always preferred and frequently required.


```xml
<key>NSAppTransportSecurity</key>
    <dict>
        <key>NSExceptionDomains</key>
        <dict>
            <key>bluekai.com</key>
            <dict>
                <key>NSExceptionRequiresForwardSecrecy</key>
                <false/>
                <key>NSIncludesSubdomains</key>
                <true/>
            </dict>
            <key>bkrtx.com</key>
            <dict>
                <key>NSExceptionRequiresForwardSecrecy</key>
                <false/>
                <key>NSIncludesSubdomains</key>
                <true/>
            </dict>
        </dict>
    </dict>
```

Passing values to the SDK

To pass a single key value pair to the SDK, use this method:

    [blueKaiSdk updateWithKey:@"myKey" andValue:@"myValue"];

To pass multiple of key value pairs to the SDK, create an NSDictionary with key/value pairs and use this method:

    [blueKaiSdk updateWithDictionary:@{@"myKey1":@"myValue1", @"myKey2":@"myValue2"}];

Resuming data posts

The resume() method in the SDK should be invoked from the calling view controller’s appCameToForeground() method. This method ensures that any queued data is sent. Queued data may not have been sent because the application was closed while data upload was in progress or because of network issues.

Create a notification in the viewDidLoad method or another location:

```objective-c
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(appCameToForeground) name:UIApplicationWillEnterForegroundNotification object:nil];
```

Define a method appCameToForeground and call resume():

```objective-c
- (void)appCameToForeground
{
   [blueKaiSdk resume];
}
```

Optionally declare the SDK delegate in ViewController.h if you need a callback when data is posted to the Oracle Data Cloud server.


```objective-c
#import "BlueKai.h"

@interface ViewController : UIViewController <BlueKaiOnDataPostedListener>

@end
```

Set ViewController as the delegate. You can place this code immediately after the initialization code.

```objective-c
blueKaiSdk = [[Bluekai alloc]initWithSiteId:@"2" withAppVersion:version withDevMode:NO];
blueKaiSdk.delegate = (id) <BlueKaiOnDataPostedListener> self;
```

To get callbacks about the status of data posting, implement the following delegate method in ViewController.h.

```objective-c
- (void)onDataPosted:(BOOL)status {
    if (status) {
        // ... react to data being posted to BlueKai...
    }
}
```

When data is posted successfully, the status is set to YES. If posting failed, the status is NO.

Sending the application display name by default

Oracle recommends that apps should send the display name of the application in addition to the site id:

```objective-c
    NSDictionary *infoPList = [[NSBundle mainBundle] infoDictionary];
    NSString *displayName = [infoPList objectForKey:@"CFBundleDisplayName"];
    [blueKaiSdk updateWithKey:@"displayName" andValue:displayName];
```

Public Methods

delegate

Sets a delegate for callbacks. This method works in conjunction with the onDataPosted method.

```objective-c
@property (nonatomic, weak) id <BlueKaiOnDataPostedListener> delegate;

devMode

Sets developer mode (YES or NO).

```objective-c
@property (nonatomic) BOOL devMode;
```

isLoggingEnabled

Enables SDK request logging (YES or NO).

```objective-c
@property (nonatomic) BOOL isLoggingEnabled;
```

NSString

Sets the site id.

```objective-c
@property (nonatomic) NSString *siteId;

Sets the calling application version number.

```objective-c
@property (nonatomic) NSString *appVersion;

UIViewController

Sets the ViewController instance to get notification on the data posting status.

```objective-c
@property (nonatomic) UIViewController *viewController;
```

useHttps

Enables the HTTPS transfer protocol. You should use HTTPS unless there is no way to avoid it.

```objective-c
@property (nonatomic) BOOL useHttps;
```

Methods

initDirectAutoIdfaEnabledWithSiteId

Creates the SDK instance with the arguments required for direct connection using the NSURLConnection object provided by Apple. The IDFA is grabbed automatically unless the user has blocked it.

```objective-c
- (id)initDirectAutoIdfaEnabledWithSiteId:(NSString *)siteID withAppVersion:(NSString *)version withDevMode:(BOOL)devMode;
```

initDirectWithSiteId

Create the instance for SDK with required arguments for direct connection using the NSURLConnection object provided by Apple. The IDFA is provided manually.

```objective-c
- (id)initDirectWithSiteId:(NSString *)siteID withAppVersion:(NSString *)version withIdfa:(NSString *)idfa withDevMode:(BOOL)devMode;
```

resume

Resumes the Oracle Data Cloud process after the calling application resumes or comes to foreground. Use in the onResume() method of the calling activity foreground.

```objective-c
- (void)resume
```

setOptInPreference

Sets user opt-in or opt-out preference.

```objective-c - (void) setOptInPreference:(BOOL)OptIn

```

updateWithDictionary

Sets key/value strings in a NSDictionary and sends them to the Oracle Data Cloud server.

```objective-c
- (void)updateWithDictionary:(NSDictionary *)dictionary
```

updateWithKey

Sets key/value strings and sends them to the Oracle Data Cloud server.

```objective-c
- (void)updateWithKey:(NSString *)key andValue:(NSString *)value
```

onDataPosted

Allows your app to receive a callback from the SDK when data has been posted to servers.

```objective-c
- (void)onDataPosted:(BOOL)status;
```

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.