Integration Steps – React Native Plug-In for iOS

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:

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") {
      } else if (eventName === "onInterstitialClicked") {
      } else if (eventName === "onInterstitialShown") {
      } else if (eventName === "onInterstitialFailed") {
      } else if (eventName === "onInterstitialDismissed") {
      } else {
        console.log("unknown event");
      }
    });

ChocolateReactBridge.subscribeToRewardCallbacks((eventName, rewardName = '', rewardAmount = 0) => {
      if(eventName === "onRewardedLoaded") {
      } else if (eventName === "onRewardedCompleted") {
        console.log("reward ad done, awarded " + rewardAmount + ' ' + rewardName );
      } else if (eventName === "onRewardedShown") {
      } else if (eventName === "onRewardedFailed") {
      } else if (eventName === "onRewardedShowFailed") {
      } else if (eventName === "onRewardedDismissed") {
      } 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.


ChocolateReactBridge.loadInterstitialAd("API_KEY_GOES_HERE");
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 app

Once the app logic is complete, you can let ReactNative generate an iOS Xcode project with the native app:

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.

 

Efficiency, Targeting Information and Privacy Settings (Optional)

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

    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:

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

    Providing location information:

    
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
);

    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.

 

6. 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.