Integration Steps for Cordova iOS

Cordova Plugin Overview

Cordova plugin contains a JS file and one .m file (For iOS). JS file is used to communicate on HTML, JS side and .m file is used to communicate with Native code. Cordova provides methods to communicate between these two plugin files.

Flow of Cordova Plugin communication:

Publisher JS code call -> Cordova Plugin JS code -> Cordova Plugin Native code -> Device/Native Code

The reverse path is taken for callbacks.

Chocolate Cordova Plugin supports the following ad units:

• Full Screen Interstitial

• Rewarded Video

 

Integration Steps

1. Prerequisites

The following prerequisites must be met for integrating Chocolate SDK with iOS.

Software Requirement

• Xcode 8 or later

• https://cordova.apache.org/#getstarted

Hardware Requirement

• Device/simulator (with iOS 8.x or later)

2. Add the Chocolate Platform plugin

Go into the root of your Cordova app (the directory containing config.xml) in Terminal and run the following command:

 cordova plugin add chocolateplatform-plugin-cordova
3. Integrate the Chocolate Platform iOS SDK

Like integration of the SDK into native apps, this can be done either manually or using the Cocoapods system. However, if you choose to use Cocoapods, the actual integration should be managed by Cordova.

3A. Integrating with Cocoapods

First, you need to add another plugin to enable Cordova to work with cocoapods:

cordova plugin add cordova-plugin-cocoapod-support

Then, edit the Cordova app’s config.xml file to list the ad sources you would like Chocolate Mediation to include.

<platform name="ios">
 <!-- Other ios configuration elements -->
  
  <pod name="ChocolatePlatform-SDK-AdColony" version="~>1.0" />
  <pod name="ChocolatePlatform-SDK-AppLovin" version="~> 1.0" />
  <pod name="ChocolatePlatform-SDK-Baidu" version="~> 1.0" />
  <pod name="ChocolatePlatform-SDK-Chartboost" version="~> 1.0" />
  <pod name="ChocolatePlatform-SDK-Facebook" version="~> 1.0" />
  <pod name="ChocolatePlatform-SDK-Flurry" version="~> 1.0" />
  <pod name="ChocolatePlatform-SDK-Google" version="~> 1.0" />
  <pod name="ChocolatePlatform-SDK-Inmobi" version="~> 1.0" />
  <pod name="ChocolatePlatform-SDK-Mopub" version="~> 1.0" />
  <pod name="ChocolatePlatform-SDK-Tapjoy" version="~> 1.0" />
  <pod name="ChocolatePlatform-SDK-Unity" version="~> 1.0" />
  <pod name="ChocolatePlatform-SDK-Vungle" version="~> 1.0" />
</platform>

If you want to only present Chocolate Platform’s native ads, and use none of the above mediation partners, put the following in the xml:

<pod name="ChocolatePlatform-SDK-Core" version="~> 2.5" />

All of the partner pods have the core SDK as a dependency, and will automatically download it if included in the Podfile. You only need to explicitly include the Core pod if you do not wish ads from any source but Chocolate.

After the file is processed by Cordova, it will be sanitized. In particular, the version flags will look as following:

version="~&gt; 1.0"

This is not an error; either format works when editing manually.

3B. Integrating manually

If you do not wish to use Cocoapods, you can integrate Chocolate Platform manually. First, download the SDK:

Download your SDK

Unzip the archive on your local machine. In the folder, there is a Plugins/cordova-manual-integration folder containing a plugin.xml file, containing the adapter list:

Edit this file, keeping only the sections for the ad networks you would like to use, and save it. Then run the following command:

This will create a com.chocolateplatform.plugin.manual.integration directory in the plugins folder of your Cordova app. Move the SDK and Mediation folders from the downloaded archive into that directory before you have cordova generate the Xcode project.

When Cordova generates your iOS app, all the necessary content will be included.

 4. Configuring the generated iOS App

When you run

An Xcode project will be generated in platforms/ios under your project directory. Open the workspace with Xcode and adjust the following settings:

a) If you used the manual integration as outlined above, and have included Google ads as one of the ad networks you wish Chocolate to mediate, select your app target in the project pane. Go to general tab and add GoogleInteractiveMediaAds.framework in Embedded Binaries. Then go to the “Build Phases” tab and add a run script phase to strip.

b) Go to Project -> Build Settings -> Other linker flags

Add “-ObjC” and “-fobjc-arc”

Whether you integrated manually or via cocoapods:

c)

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

d) Preparing Your Apps for iOS 10

Disable ATS – to ensure non-secure content from the partners work correctly in your updated apps.

 

Set up the following keys in your app’s info.plist:

NSAllowsArbitraryLoads: No

NSAllowsArbitraryLoadsForMedia:No

NSAllowsArbitraryLoadsInWebContent: NO

 

 

NOTE: If you are enabling AdColony demand, follow below steps. If you are not using AdColony, skip below steps.

 

 

e) 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:

 

f) 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:

 

 

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

 

5. Integrating Full Screen Interstitial Ad Unit

Interstitial ads provide full-screen experiences, commonly incorporating rich media to offer a higher level of interactivity. Interstitials are typically shown during natural transitions in your app, e.g. after completing a game level, or while waiting for a new view to load. You can use the LVDOInterstitialAd object and its associated listeners to fetch and display interstitial ads in your app.

Integration Steps

1. In your html, add the code below to include the vdopiaPlugin

 

2. Decide what events should trigger loading of an interstitial ad, and if necessary, setup the appropriate UI. For example, in order to start loading an on a press of a button,  create a button with an appropriate callback:

And implement that callback in the JavaScript (see below).

3. In JavaScript, call SDK to load interstitial ad

4. Add interstitial ad callback methods

5. Decide what events should trigger showing of an interstitial ad, and if necessary, setup the appropriate UI. For example, in order to start loading an on a press of a button,  create a button with an appropriate callback:

And implement that callback in the JavaScript (see below).

You can also place the call to show that in the interstitialAdEvent callback for onInterstitialLoaded:

 

6. Integrating Rewarded Video Ad Unit

Fetch a rewarded video ad

 

1. In your html, add the code below to include the vdopiaPlugin

2. Decide what events should trigger loading of an interstitial ad, and if necessary, setup the appropriate UI. For example, in order to start loading an on a press of a button,  create a button with an appropriate callback:

And implement that callback in the JavaScript (see below).

3. In JavaScript, call SDK to load reward ad

4. Configure rewarded video ad callback methods

 

5. Decide what events should trigger showing of a reward ad, and if necessary, setup the appropriate UI. For example, in order to start loading an on a press of a button,  create a button with an appropriate callback:

And implement that callback in the JavaScript (see below).

 

You can also place the call to show the ad in the rewardAdEvent callback for rewardedVideoDidLoadAd:

Reward Handling

You have two options in terms of reward handling.

[Server Callback]

Server Callbacks allow user rewards to be sent directly from our servers to yours. Our servers send a real-time notification as soon as a reward is logged in our system. Your servers will then need to be able to process the reward as soon as it comes in, and then populate the reward out to the user.

The main benefit of server-side callbacks is that all traffic directly related to crediting the reward is completely outside the control or visibility of the user. Because there is no sensitive traffic going through the user’s device, there is less chance for fraud.

For server callback setup, please log in to portal and utilize the following resources:

  • Callback Security Secret – If you want to enable verification via ‘digest’, you will need this.
  • Macro Details List – Shows list of supported macros. Also find the details of ‘digest’ from here.
  • Callback Tester – Use this tool to have our server ping your server to test the connectivity between our server and yours.

 

[Client Callback]

If you plan on handling the user rewarded via your own code and your systems, please choose this option. You can use the function below for rewarding the user:

7. Targeting, privacy, and initialization
    1. TargetingYou 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.
    2. PrivacyOn 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.

      In the United States, the Children’s Online Privacy Protection Act (COPPA) limits collection of data from children. If your target audience is children under 13, this information should be provided to the SDK:

    3. InitializationFor faster display of ads, you can pre-initialize the SDK before ad requests — ideally, as soon as your app loads:

How to turn on ads on your ad unit

Please send us your sample app with the integrated code. We will help you validate the SDK setup and turn on the demand.

You can contact us via email: sdk-support@chocolateplatform.com