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="~> 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:
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:
<!-- AdColony Adapter --> <source-file src="SDK/libChocolatePlatform-SDK-AdColony.a" framework="true"/> <framework src="Mediation/AdColony/AdColony.framework" custom="true"/> <!-- AppLovin Adapter --> <source-file src="SDK/libChocolatePlatform-SDK-AppLovin.a" framework="true"/> <framework src="Mediation/AppLovin/AppLovinSDK.framework" custom="true"/> <!-- Baidu Adapter --> <source-file src="SDK/libChocolatePlatform-SDK-Baidu.a" framework="true"/> <framework src="Mediation/Baidu/DUModuleSDK.framework" custom="true"/> <!-- Chartboost Adapter --> <source-file src="SDK/libChocolatePlatform-SDK-Chartboost.a" framework="true"/> <framework src="Mediation/Chartboost/Chartboost.framework" custom="true"/> <!-- Facebook Adapter --> <source-file src="SDK/libChocolatePlatform-SDK-Facebook.a" framework="true"/> <framework src="Mediation/FacebookFramework/FBAudienceNetwork.framework" custom="true"/> <!-- Flurry Adapter --> <source-file src="SDK/libChocolatePlatform-SDK-Flurry.a" framework="true"/> <source-file src="Mediation/Flurry/Flurry/libFlurry_8.5.0.a" framework="true"/> <source-file src="Mediation/Flurry/FlurryAds/libFlurryAds_8.5.0.a" framework="true"/> <!-- Google Adapter --> <source-file src="SDK/libChocolatePlatform-SDK-Google.a" framework="true"/> <framework src="Mediation/Google/GoogleInteractiveMediaAds.framework" custom="true"/> <framework src="Mediation/Google/GoogleMobileAds.framework" custom="true"/> <!-- InMobi Adapter --> <source-file src="SDK/libChocolatePlatform-SDK-Inmobi.a" framework="true"/> <framework src="Mediation/InMobiLibs/InMobiSDK.framework" custom="true"/> <!-- Mopub Adapter --> <source-file src="SDK/libChocolatePlatform-SDK-Mopub.a" framework="true"/> <source-file src="Mediation/mopub/libMopubSDK.a" framework="true"/> <framework src="Mediation/mopub/MPUBMoatMobileAppKit.framework" custom="true"/> <!-- Tapjoy Adapter --> <source-file src="SDK/libChocolatePlatform-SDK-Tapjoy.a" framework="true"/> <framework src="Mediation/Tapjoy.embeddedframework/Tapjoy.framework" custom="true"/> <resource-file src="Mediation/Tapjoy.embeddedframework/Resources/TapjoyResources.bundle" /> <!-- Unity Adapter --> <source-file src="SDK/libChocolatePlatform-SDK-Unity.a" framework="true"/> <framework src="Mediation/unity/UnityAds.framework" custom="true"/> <!-- Vungle Adapter --> <source-file src="SDK/libChocolatePlatform-SDK-Vungle.a" framework="true"/> <framework src="Mediation/vungle/VungleSDK.framework" custom="true"/>
Edit this file, keeping only the sections for the ad networks you would like to use, and save it. Then run the following command:
cordova plugin add /path/to/unzipped/sdk/archive/Plugins/cordova-manual-integration
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
cordova build ios
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
<key>NSAppTransportSecurity</key> <dict> <key>NSAllowsArbitraryLoads</key> <false/> <key>NSAllowsArbitraryLoadsForMedia</key> <false/> <key>NSAllowsArbitraryLoadsInWebContent</key> <false/> </dict>
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:
<key>LSApplicationQueriesSchemes</key> <array> <string>fb</string> <string>instagram</string> <string>tumblr</string> <string>twitter</string> </array>
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:
<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>
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
<script type="text/javascript" src="plugins/com.chocolateplatform.plugin.cordova/src/js/jquery.js"></script> <script type="text/javascript" src="plugins/com.chocolateplatform.plugin.cordova/src/js/vdopiaPlugin.js"></script>
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:
<button onclick="loadInterstitialAd()">Load Interstitial Ad</button>
And implement that callback in the JavaScript (see below).
3. In JavaScript, call SDK to load interstitial ad
function loadInterstitialAd()
{
console.log("Interstitial Ad Start");
chocolate.registerInterstitialAdEvents(this);
// Use the SSP API Key you obtained from your Chocolate contact or portal
var apikey = localStorage.getItem('apikey') || 'YOUR_API_KEY';
chocolate.loadInterstitialAd(apikey);
}
4. Add interstitial ad callback methods
function interstitialAdEvent(message)
{
if (message === "onInterstitialLoaded")
{
}
else if (message === "onInterstitialFailed")
{
}
else if (message === "onInterstitialShown")
{
}
else if (message === "onInterstitialDismissed")
{
}
else if (message === "onInterstitialClicked")
{
}
}
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:
<button onclick="showInterstitialAd()">Load Interstitial Ad</button>
And implement that callback in the JavaScript (see below).
function showInterstitialAd()
{
chocolate.showInterstitialAd();
}
You can also place the call to show that in the interstitialAdEvent callback for onInterstitialLoaded:
function interstitialAdEvent(message)
{
if (message === "onInterstitialLoaded")
{
chocolate.showInterstitialAd();
}
else if (message === "onInterstitialFailed")
{
}
else if (message === "onInterstitialShown")
{
}
else if (message === "onInterstitialDismissed")
{
}
else if (message === "onInterstitialClicked")
{
}
}
6. Integrating Rewarded Video Ad Unit
Fetch a rewarded video ad
1. In your html, add the code below to include the vdopiaPlugin
<script type="text/javascript" src="plugins/com.chocolateplatform.plugin.cordova/src/js/jquery.js"></script> <script type="text/javascript" src="plugins/com.chocolateplatform.plugin.cordova/src/js/vdopiaPlugin.js"></script>
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:
<button onclick="loadRewardAd()">Load Reward Ad</button>
And implement that callback in the JavaScript (see below).
3. In JavaScript, call SDK to load reward ad
function loadRewardAd() {
console.log("Load Reward Ad Start");
chocolate.registerRewardAdEvents(this);
// Use the SSP API Key you obtained from your Chocolate contact or portal
var apikey = localStorage.getItem('apikey') || 'YOUR_API_KEY';
chocolate.loadRewardAd(apikey);
}
4. Configure rewarded video ad callback methods
function rewardedAdEvent(message)
{
if (message === "rewardedVideoDidLoadAd")
{
}
else if (message === "rewardAdFailedWithError")
{
}
else if (message === "rewardedVideoDidFinish")
{
}
else if (message === "rewardedVideoDidStartVideo")
{
}
else if (message === "rewardedVideoDidFailToStartVideoWithError")
{
}
else if (message === "rewardedVideoWillDismiss")
{
}
}
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:
<button onclick="showRewardAd()">Show Reward Ad</button>
And implement that callback in the JavaScript (see below).
function showRewardAd()
{
// Parameter sequence for showRewardAdFunctionCallFromHtml function
// 1. REWARD_AMOUNT
// 2. REWARD_NAME
// 3. REWARD_USER_ID
// 4. REWARD_SECRET_KEY - Please obtain this from the portal
chocolate.showRewardAd("30","coin","CordovaUser","qj5ebyZ0F0vzW6yg");
}
You can also place the call to show the ad in the rewardAdEvent callback for rewardedVideoDidLoadAd:
function rewardedAdEvent(message)
{
if (message === "rewardedVideoDidLoadAd")
{
chocolate.showRewardAdFunctionCallFromHtml(REWARD_AMOUNT,REWARD_NAME,REWARD_USER_ID,REWARD_SECRET_KEY)
}
else if (message === "rewardAdFailedWithError")
{
}
else if (message === "rewardedVideoDidFinish")
{
}
else if (message === "rewardedVideoDidStartVideo")
{
}
else if (message === "rewardedVideoDidFailToStartVideoWithError")
{
}
else if (message === "rewardedVideoWillDismiss")
{
}
}
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:
function rewardedAdEvent(message)
{
if (message === "rewardedVideoDidFinish")
{
}
}
7. Targeting, privacy, and initialization
-
- 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.
// Please find the descriptions below // These will be used for better targeting of the ads // You can pass empty string for any param as in "" // Param 1: Age // Param 2: BirthDate (dd/mm/yyyy) // Param 3: Gender (m/f/u) // Param 4: Marital status (single/married/unknown) // Param 5: Ethincity (Example: Africans/Asian/Russians) // Param 6: DMA code (in string format) // Param 7: User Registration Postal Code (in string format) // Param 8: Current Postal Code (in string format) // Param 9: Location - Latitude (in string format) // Param 10: Location - Longitude (in string format) chocolate.setDemographics("23","23/11/1990","m","single","Asian"); chocolate.setLocation("999","94539", "94539","28.70","77.10"); // Please find the setAdRequestAppParams descriptions below // Param 1: appName (Application Name) // Param 2: pubName (Publisher Name) // Param 3: appDomain (App domain name) // Param 4: pubDomain (publisher Domain) // Param 5: storeUrl - URL encoded (App store URL of application) // Param 6: iabCategory (IAB category ) chocolate.setAppInfo("CordovaDemo", "Chocolate", "cordova-demo.com", "your-domain.com", "app-store-url-url-encoded.com", "IAB9"); - 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.
chocolate.setPrivacySettings( false, //gdpr applies null //gdpr consent string );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:
chocolate.setCoppaStatus(true); - InitializationFor faster display of ads, you can pre-initialize the SDK before ad requests — ideally, as soon as your app loads:
chocolate.initWithAPIKey(YOUR_API_KEY_GOES_HERE);
- 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.
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
