iOS – Project Setup Part II

 

To use the location services which can be used to pass on the location information as part of the ad request, add a key, “NSLocationWhenInUseUsageDescription”, and set the value in string for the alert message in info.plist file of your project. Please refer to the screenshot below.

BitCode Support

Bitcode for Chocolate SDK is enabled by default. You can configure your Bitcode setting under ‘Build Settings > Build Options > Enable Bitcode’. If you wish to disable, you can set this value to ‘No’.

Using AdColony Demand SDK?

If your project doesn’t support ARC, add the following linker flag to ‘Target > Build Settings >Linking > Other Linker Flags’

 -fobjc-arc (this allows AdColony to use ARC even if your project does not)

 

Configuring URL Schemes

With the release of iOS 9, Apple also restricted usage of the canOpenURL: API, which AdColony uses to make decisions about whether or not we can land users in certain apps from our Dynamic End Cards (DECs). In order to enable deep-linking for the apps the AdColony SDK uses, please add the following entry to your app’s plist.

<key>LSApplicationQueriesSchemes</key> 
 <array>
 <string>fb</string>
 <string>instagram</string>
 <string>tumblr</string>
 <string>twitter</string>
 </array>

 

Configuring Privacy Controls

In iOS 10, Apple has extended the scope of its privacy controls by restricting access to features like the camera, photo library, etc. In order to prevent your app from crashing when the AdColony SDK uses these services, you will need to add the following entry to your apps plist:

<key>NSCalendarsUsageDescription</key>
<string>Adding events</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Taking selfies</string>
<key>NSCameraUsageDescription</key>
<string>Taking selfies</string>
<key>NSMotionUsageDescription </key>
<string>Interactive ad controls</string>

 

Mediation Partner SDK Versions

Partner Name SDK Version
AdColony 4.1.2
Amazon 3.3.0
AppLovin 6.11.1
Facebook 5.1
Flurry 8.5.0
Google AdMob 7.53.1
Google IMA 3.11.1
Mopub 5.10.0
Tapjoy 12.4.0
Unity Ads 3.4.0
Vungle 6.4.6
Criteo 3.2.0

 

Notes

The AppLovin and Google IMA SDKs are only compatible with iOS 9.0 and above.

Google Admob SDK requires placing your Admob App ID in the iOS app’s Info.plist file under the key GADApplicationIdentifier:

 

 

Likewise, AppLovin requires placing your AppLovin SDK key in the Info.plist file under the key AppLovinSdkKey.

 

Chocolate SDK Initialization

Please initialize Chocolate SDK soon after the app launch – i.e. in the application:didFinishLaunchingWithOptions: method of AppDelegate.

[ChocolatePlatform initWithAdUnitID:@“API_KEY_GOES_HERE”];

Please contact Chocolate to obtain your App API key. You can contact us at sdk-support@vdopia.com

You should now be able to rebuild your project without any errors.

 

 

Ad targeting setup

You can provide the Chocolate Platform SDK information useful for targeting ads to your audience. Although this is optional, it can result in higher yield. The information used for targeting is of three types: about the user, about the location, and about the app.

Import libraries

In your app delegate, we can initialize elements needed to obtain this information, such as CoreLocation. First, we start by importing the following header files.

#import <CoreLocation/CoreLocation.h>
@import ChocolatePlatform_SDK_Core;
Declare CLLocationManager instance
@interface AppDelegate : UIResponder <UIApplicationDelegate,CLLocationManagerDelegate>
{
 CLLocationManager *locationManager;
 BOOL findLocation;
}

Use Core Location to obtain the device’s current geographic location, if you want to. Then provide it to the SDK for targeting, along with other data.

 

- (void)provideTargetingInfo:(CLLocation *)location{

    //Demographic data
    ChocolatePlatformDemographics *dem = [ChocolatePlatform demographics];
    [dem setBirthdayYear:1990 month:2 day:12];
    dem.gender = ChocolatePlatformGenderMale;
    dem.maritalStatus = ChocolatePlatformMaritalStatusMarried;
    dem.ethnicity = @"Asian";
    dem.age = 28;
    
    //location data
    ChocolatePlatformLocation *loc = [ChocolatePlatform location];
    loc.location = location;
    loc.dmacode = @"327788";
    loc.currpostal = @"122001";
    loc.postalcode = @"122016";
    loc.metro = @"XYZ";
    loc.geo = @"India:Haryana:Gurgaon";

    //app data
    // For description of the parameters, please refer to API documentation https://vdopia.atlassian.net/wiki/spaces/RC/pages/34177028/Web+Server+Ad+API+-+v1.1 
    ChocolatePlatformAppInfo *ai = [ChocolatePlatform appInfo];
    ai.keywords = @[@"BOOK",@"MOVIES",@"GAMES",@"APPS"];
    ai.appDomain = @"wordswithfriends.com";
    ai.Category = @"IAB2";
    ai.requester = @"Rovio";
    ai.publisherdomain = @"rovio.com";
    ai.appStoreUrl = @"https://itunes.apple.com/";
}

 

Compliance with GDPR

On May 25, 2018, the EU General Data Protection Regulation (GDPR) will come into effect. IAB Europe has created a standard framework for technical compliance with this law. You can learn more here.

GDPR makes consent for collection and usage of data opt-in, requiring explicitly asking the end user for their consent and informing them of the purpose of such data collection. By default, consent will be denied, meaning only generic, not-targeted ads can be shown to users within the EU.

Obtaining consent should produce two pieces of information: a boolean flag noting whether compliance GDPR applies in the specific instance of the current user, and a consent string encoding the actual data usage permissions the user consented to. This information can then be passed on to the Chocolate Platform SDK using the ChocolatePlatformPrivacySettings class.

ChocolatePlatformPrivacySettings *priv = [ChocolatePlatform privacySettings];
[priv subjectToGDPR:YES withConsent:nil]; //passing in nil will deny consent for data usage 

Where

  • subjectToGDPR
    • Set this to YES if the user is subject to GDPR
    • Set this to NO if the user is not subject to GDPR
  • withConsent
    • GDPR consent string in official IAB format. nill will be interpreted as user has opted-out of all consent for all vendors.

Don’t have a CMP (consent management platform) solution yet? Don’t worry – if none of the GDPR values are configured, our mediation code will fall back to internal logic and handle the mediation in GDPR compliant way.

 

Example sample code
#import <CoreLocation/CoreLocation.h>
@import ChocolatePlatform_SDK_Core;
@interface AppDelegate : UIResponder <UIApplicationDelegate,CLLocationManagerDelegate>
{
CLLocationManager *locationManager;
BOOL findLocation;
}
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
// Override point for customization after application launch.
[[UIApplication sharedApplication]setStatusBarHidden:YES];
findLocation = YES;
locationManager = [[CLLocationManager alloc] init];
locationManager.delegate = self;
locationManager.desiredAccuracy = kCLLocationAccuracyBest;
if ([locationManager respondsToSelector:@selector(requestWhenInUseAuthorization)]) {
[locationManager requestWhenInUseAuthorization];
}
[locationManager startUpdatingLocation];
return YES;
}
- (void)dealloc
{
locationManager = nil;
}
#pragma mark - CLLocationManagerDelegate
- (void)locationManager:(CLLocationManager *)manager didFailWithError:(NSError *)error
{
if (findLocation)
{
CLLocation *clocation = [[CLLocation alloc] initWithLatitude:0.0 longitude:0.0];
[self performSelectorOnMainThread:@selector(provideTargetingInfo:) withObject:clocation waitUntilDone:NO];
}
findLocation = NO;
}
- (void)locationManager:(CLLocationManager *)manager didUpdateToLocation:(CLLocation *)newLocation fromLocation:(CLLocation *)oldLocation
{
CLLocation *currentLocation = newLocation;
if (currentLocation != nil) {
if (findLocation)
{
[self performSelectorOnMainThread:@selector(provideTargetingInfo:) withObject:currentLocation waitUntilDone:NO];
}
}
else
{
if (findLocation)
{
CLLocation *clocation = [[CLLocation alloc] initWithLatitude:0.0 longitude:0.0];
[self performSelectorOnMainThread:@selector(provideTargetingInfo:) withObject:clocation waitUntilDone:NO];
}
}
findLocation = NO;
}
- (void)provideTargetingInfo:(CLLocation *)location
{
//Demographic data
    ChocolatePlatformDemographics *dem = [ChocolatePlatform demographics];
    [dem setBirthdayYear:1990 month:2 day:12];
    dem.gender = ChocolatePlatformGenderMale;
    dem.maritalStatus = ChocolatePlatformMaritalStatusMarried;
    dem.ethnicity = @"Asian";
    dem.age = 28;
    
    //location data
    ChocolatePlatformLocation *loc = [ChocolatePlatform location];
    loc.location = location;
    loc.dmacode = @"327788";
    loc.currpostal = @"122001";
    loc.postalcode = @"122016";
    loc.metro = @"XYZ";
    loc.geo = @"India:Haryana:Gurgaon";
    //app data
    ChocolatePlatformAppInfo *ai = [ChocolatePlatform appInfo];
    ai.keywords = @[@"BOOK",@"MOVIES",@"GAMES",@"APPS"];
    ai.appDomain = @"wordswithfriends.com";
    ai.Category = @"BOOK";
    ai.requester = @"Kellton";
    ai.publisherdomain = @"revolutionmobile.com";
    ai.appStoreUrl = @"https://itunes.apple.com/";
}
@end

Custom segment properties

The ChocolatePlatform permits adding publisher-defined properties to be sent when making ad requests. This is done using the ChocolatePlatformCustomSegmentProperties class. Each property is a string value associated with a string key; the values of both are chosen by the publisher.

Setting a custom property


[ChocolatePlatformCustomSegmentProperties setCustomSegmentProperty:@"com.mygame.userName" with:@"Roger"]; //sets the "com.mygame.userName" property value to "Roger"
[ChocolatePlatformCustomSegmentProperties setCustomSegmentProperty:@"com.mygame.topLevel" with:@"15"]; //User "Roger" has reached level 15

Calling the setCustomSegmentProperty method on the same key with a new value overrides the existing value, and the new value will be sent subsequently. You can inspect the currently set properties.

Getting current custom property values


[ChocolatePlatformCustomSegmentProperties getCustomSegmentProperty:@"com.mygame.userName"];  
[ChocolatePlatformCustomSegmentProperties getAllCustomSegmentProperties];

The getCustomSegmentProperty will return nil if the property has not been set. The getAllCustomSegmentProperties method will return an empty dictionary if no properties have been set.

Deleting custom properties

Once set, custom segment properties persist from app session to app session, unless their values are set again. To stop sending the values, the properties have to be explicitly deleted:


[ChocolatePlatformCustomSegmentProperties deleteCustomSegmentProperty:@"com.mygame.userName"];  
[ChocolatePlatformCustomSegmentProperties deleteAllCustomSegmentProperties];

iOS Sample App on GitHub

A working sample app illustrating the integration and use of the SDK for all types of ad units can be found on GitHub. The SDK is integrated via the CocoaPods system, and the app is setup to display various ad units as the user chooses.

Next, let’s enable your ad unit.

Recent Changes

  • New! (2/3/2020) Our AppLovin and MoPub adapters now support Banner 320×50
  • Bug fix for banner ads in scroll views
  • Updated to use latest versions of partner SDKs
  • Now supports Banner 300×250, 320×50, 728×90 (tablet)