Playing Chocolate Ads in apps made with ReactNative

ReactNative is an SDK that allows cross-platform mobile app development. A plugin allows you to link such an app to Chocolate Platform’s ad SDK, and run interstitial and rewarded video ads.

Creating a ReactNative running Chocolate ads can be done with the following steps:

 

1. Obtaining the plugin

Install the plugin via npm ( within your React Native project root folder ):

npm install chocolateplatform-plugin-react

 

2. Linking the plugin

At the head of the code file where you intend to run ads according to your app’s logic, import the plugin:


import ChocolateReactBridge from 'chocolateplatform-plugin-react';

 

3. Subscribing to callbacks

Chocolate provides callbacks at important ad related events. You can subscribe to events related to interstitial ads, rewarded ads, or both:


ChocolateReactBridge.subscribeToInterstitialCallbacks((eventName) => {
if(eventName === "onInterstitialLoaded") {

  //Right after calling 'loadInterstitialAd', if there is a fill, 
  //this 'onInterstitialLoaded' event will get triggered.
  //This is when you want to show the interstitial ad.

  ChocolateReactBridge.showInterstitialAd();

} else if (eventName === "onInterstitialClicked") {

} else if (eventName === "onInterstitialShown") {

} else if (eventName === "onInterstitialFailed") {

  //This event will happen when you call 'loadInterstitialAd'
  //and it could not get an ad or there was some error while
  //fetching the ad.
  
  //DO NOT call 'loadInterstitialAd' here. DO call pre-fetch.
  //Pre-fetch will not produce any callback events.

  ChocolateReactBridge.prefetchInterstitialAd("YOUR_API_KEY");

} else if (eventName === "onInterstitialDismissed") {

  //We recommend pre-fetching the next ad for better performance
  //when the user dismisses the current interstitial ad.
  //NOTE: There will be no event callback for pre-fetch calls.

  ChocolateReactBridge.prefetchInterstitialAd("YOUR_API_KEY");

} else {
  console.log("unknown event");
}
});

ChocolateReactBridge.subscribeToRewardCallbacks((eventName, rewardName = '', rewardAmount = 0) => {
if(eventName === "onRewardedLoaded") {

  //Right after calling 'loadRewardAd', if there is a fill, 
  //this 'onRewardedLoaded' event will get triggered.
  //This is when you want to show the reward ad.

  ChocolateReactBridge.showRewardAd("Coins", 50, "myUserId", "secret-12345678");

} else if (eventName === "onRewardedCompleted") {

  console.log("reward ad done, awarded " + rewardAmount + ' ' + rewardName );

} else if (eventName === "onRewardedShown") {

} else if (eventName === "onRewardedFailed") {

  //This event will happen when you call 'loadRewardAd'
  //and it could not get an ad or there was some error while
  //fetching the ad.
  
  //DO NOT call 'loadRewardAd' here. DO call pre-fetch.
  //Pre-fetch will not produce any callback events.

  ChocolateReactBridge.prefetchRewardAd("YOUR_API_KEY");

} else if (eventName === "onRewardedShowFailed") {

} else if (eventName === "onRewardedDismissed") {


  //We recommend pre-fetching the next ad for better performance
  //when the user dismisses the current interstitial ad.
  //NOTE: There will be no event callback for pre-fetch calls.

  ChocolateReactBridge.prefetchRewardAd("YOUR_API_KEY");


} else {
console.log("unknown event");
}
});

For the rewarded ads, only the onRewardedCompleted callback will provide the rewardName and rewardAmount parameters.

 

3.1 Reward Handling (for Rewarded Video Ad Unit Only)

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 should be able to use the callback below.

onRewardedCompleted

 

4. Launching the ad

This occurs in two steps: first, you load the ad type you want, passing in the API key provided by Chocolate.


//Note: Do not call both at the same time.
ChocolateReactBridge.loadInterstitialAd("API_KEY_GOES_HERE"); //You may use "XqjhRR" as a test api key
//OR
ChocolateReactBridge.loadRewardAd("API_KEY_GOES_HERE");

If you have subscribed to the callbacks as in step 3, you will receive the onInterstitialLoaded or onRewardedLoaded callback if the ad loads successfully. Otherwise, you should receive the onInterstitialFailed or onRewardedFailed callbacks, and handle them appropriately. Once the ad successfully loads, you can play it at any time:


ChocolateReactBridge.showInterstitialAd();
ChocolateReactBridge.showRewardAd(
"coins", //reward name
100, //reward amount
"", //user ID
"" //secret key
);

 

5. Setting up the native iOS and Android app

Once the app logic is complete, you can let ReactNative generate a native iOS Xcode project and/or a native Android project for Android Studio.

For setting up a native iOS Xcode project, proceed to Step 6.

For setting up a native Android project, proceed to Step 7.

 

6. iOS Setup

react-native eject ios

The iOS app will be located in the ios folder in your app’s root directory. You can now work with that project directly. You need to do two things:

1. Integrate the Chocolate SDK and adjust the settings

You can do this with either Cocoapods or manual approach. Follow the directions up to the “Chocolate SDK Initialization” section.

2. Add the ReactNative bridge files to the project

There are two files, ChocolateReactBridge.h and ChocolateReactBridge.m. They are found in the node_modules directory in the root of your app.

Once this done, you can build the iOS app in Xcode to run on the simulator or an iOS device. Ads will play according to the app logic created in ReactNative.

 

7. Android Setup

Run the following command from your react native project root folder:

./node_modules/.bin/react-native eject android

The Android app will be created and located in the android folder in your app’s root directory. You need to do two things:

 

1. (android) Integrate the Chocolate SDK

 

Make sure you have the latest version of Android Studio.

In Android Studio, File… Open… <react native project>/android (this will open the android project).

Android Studio will show several warnings to update your project gradle version. Choose ‘yes’. We want to use the latest gradle.

Add the Chocolate SDK to the project: Follow our Android Project Setup Guide and return here when done.

You may skip the last step from that guide (Initialization) since that is covered in the Efficiency section below.

If you have any issues integrating the SDK, in particular AndroidManifest.xml and <react native project>/android/app/build.gradle, please see our React Native Android sample below, AwesomeProject. It was built following all these steps for Android so you could use it as a side-by-side reference.

 

2. (android) Add the ReactNative bridge files to the project

 

In Android Studio, navigate and open the file, MainApplication.java. At the top of the file, make a mental note of the package:

package <package-name> for example: package com.coolcompany;

Download the following 2 files and copy them into the same folder of MainApplication.java

ChocolateReactBridge.java

ChocolateReactPackage.java

In Android Studio, modify these two files. Modify their package names to be the same as the package name of MainApplication.java. The package name is declared at the top of the file.

So, if MainApplication.java has a declared package name of:

package com.coolcompany;

then, rename the package name for ChocolateReactBridge.java and ChocolateReactPackage.java to the same.

Modify MainApplication.java:

add the following import statement:

import android.support.multidex.MultiDexApplication;

Extend MultiDexApplication instead of Application. So, instead of:

public class MainApplication extends Application implements ReactApplication

We want:

public class MainApplication extends MultiDexApplication implements ReactApplication

In MainApplication.java, modify the getPackages() method and add ChocolageReactPackage as follows:

 

@Override
protected List<ReactPackage> getPackages() {
return Arrays.<ReactPackage>asList(
new MainReactPackage(),
new ChocolateReactPackage());
}

 

 

At this point, your project should be able to run and load ads.

Run this command:

<react native project>/node_modules/.bin/react-native run-android

 

3. (android) Try our React Native Android Sample:

 

AwesomeProject

Connect an android device or emulator and run the project from it’s root:

<react native project>/node_modules/.bin/react-native run-android

 

Efficiency, Targeting Information and Privacy Settings

The Chocolate SDK provides additional api calls to improve ad experience. The plugin exposes those calls to ReactNative.

  1. Efficiency

    Ad delivery can be improved by initializing the SDK early. It’s a good idea to make this call once, soon after the app launch. This will make it less likely that the first request for an ad will time out due to a lengthy initialization process.

    ChocolateReactBridge.initWithAdUnitID("API_KEY_GOES_HERE");
  2. Targeting (OPTIONAL)

    For more relevant ads more likely to result in higher yields, you can provide the Chocolate Platform SDK information useful for targeting ads to your audience. The information used for targeting is of three types: about the user, about the location, and about the app.

    Providing user information:

    
//OPTIONAL
ChocolateReactBridge.setDemographics(
20, //age
new Date(1998, 1, 1), //birthday
"male", //gender
"single", //marital status
"Asian" //ethnicity
);

    Providing location information:

    
//OPTIONAL
ChocolateReactBridge.setLocation(
"999", //DMA code
"94539", //postal code
"94539", //current postal
"28.70", //latitude
"77.10". //longitude
);

    Providing app information:

    
ChocolateReactBridge.setAppInfo(
"Angry Birds", //app name
"Rovio", //publisher name
"angrybirds.com", //app domain
"rovio.com", //publisher domain
"APP_STORE_URL_GOES_HERE", //App Store url
"IAB9" //IAB category
);
  3. Privacy

    Some jurisdictions have specific legislation pertaining to users’ online privacy and data collection by internet actors. 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:

    
ChocolateReactBridge.setCoppaStatus(true);

    The EU has enacted GDPR (General Data Protection Regulation). You can provide the relevant information to the SDK as follows:

    
ChocolateReactBridge.subjectToGDPR(
false, //subjectToGDPR (false outside EU)
null //gdprConsentString
);
//If you are unsure of what GDPR is or what you should do, then don't worry.
//This call is not mandatory. Our platform will auto-detect your GDPR status
//and act accordingly.

    Where

    • subjectToGDPR
      • Set this to true if the user is subject to GDPR
      • Set this to false if the user is not subject to GDPR
    • gdprConsentString
      • GDPR consent string in official IAB format. null 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.

 

8. 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 plugin setup and turn on demand. In the meantime, feel free to use our test api key: XqjhRR