1. Integration Steps for Cordova Android


Integration Steps for Cordova Android

 

Integrate Chocolate Platform SDK into your Cordova Android Project

 

Our Cordova Plugin Basics:

Chocolate Cordova plugin contains a few javascript files and one css file and some gradle lines.  Javascript is used to communicate on HTML, JS side and Java.  Cordova provides methods to communicate between these two worlds.

 

Flow of Cordova Plugin communication:

Publisher JS code call -> Cordova Plugin JS code which call -> Cordova Plugin Java (Native code) code which call -> Device/Native Code

Device/Native Code returns the result to -> Cordova Plugin Java file which pass result to -> Cordova Plugin JS file from there pass to -> JS file of Publisher

 

Chocolate Platform SDK Cordova plugin supports the following ad units:

     • Full Screen Interstitial

     • Rewarded Video

 

Integration Steps

 

Step 1:

Download our Cordova javascript files here

     • vdopiaPlugin.js

In your Cordova project, open file manager to assets/www and make a js folder.  Copy vdopiaPlugin.js to that folder.  And now, under assets/www make a css folder and copy the above css file there.

 

Step 2:

Add the following tag to the config.xml of your Cordova project.  The path should be res/xml/config.xml

<feature name="VdopiaPlugin">
     <param name="android-package" value="com.vdopia.plugin.VdopiaPlugin" />
 </feature>

NOTE: Do not worry about where to get VdopiaPlugin.  Just copy and paste the above lines into config.xml and follow the rest of the instructions.

 

Step 3:
Add the following lines your HTML
<script type="text/javascript" src="cordova.js"></script> //For Cordova project necessary
<script type="text/javascript" src="js/vdopiaPlugin.js"></script> //Plugin js for Vdopia plugin

 

Step 4: (big step)

Now we need to update build.gradle and AndroidManifest.xml in your Android Studio Project:

Carefully follow Steps 1-4 in our general Android Project Setup:

https://chocolateplatform.com/android/?app_dev_framework=android

 

There is a small section where it talks about including our Cordova plugin.   Return here when you’re done

and follow the instructions to start showing ads in your Cordova Android application.

 

 

That’s it. Now you are ready use our Cordova plugin to display the Ads in your Cordova Application.

 

Steps to show ads in Cordova:

• Initialize Chocolate Platform SDK:

When your application is loaded, make sure you initialize our Chocolate Platform SDK.

You may use our test key if you don’t have one yet:  XqjhRR

initializeChocolateSDK("YOUR API KEY");
• Interstitial Ad:
<button id="myButton1" title="" onclick="loadInterstitialAd()">Load Interstitial Ad</button>

<script>

function loadInterstitialAd() {
    console.log("Request Interstitial Ad");

    callbackFunction = InterstitialAdEvent;

    //APIKEY
    loadInterstitialAdFromSDK("YOUR_API_KEY");

}

function InterstitialAdEvent(message) {

   console.log("Interstitial Ad Event ::: " + message);

   if (message === "onInterstitialLoaded") {

      showInterstitialAdFromSDK();  //shows the interstitial ad

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

      //OPTIONAL: We recommend pre-fetching the next interstitial ad while
      //the current ad is being shown. This increases the chances your next 
      //ad request will be ready immediately. 

      prefetchInterstitialAdFromSDK("YOUR_API_KEY");

   }

} 

} </script>
Below is the list of events message for Interstitial Ad:
onInterstitialLoaded

onInterstitialShown

onInterstitialFailed

onInterstitialDismissed

onInterstitialClicked

 

• Rewarded Video Ad:
<html>
 <head>
    <meta name="viewport" content="width=device-width, height=device-height, user-scalable=no"/>

    <title>Vdopia Plugin Demo</title>

    <style>
         .centerDiv {
         text-align: center;
         }

        .centerDialog {
         top:40%;
         width: 50%;
         text-align: center;
         }

        button {
         background-color: #4CAF50;
         border: none;
         color: white;
         padding: 15px 32px;
         text-align: center;
         width: 60%;
         border-radius: 8px;
         text-decoration: none;
         display: inline-block;
         font-size: 16px;
         }

        .centerDialog button {
             width: 95%;
         }

        button:disabled {
         opacity: 0.60;
         cursor: not-allowed;
         }
     </style>

    <script type="text/javascript" src="cordova.js"></script>
    <script type="text/javascript" src="js/vdopiaPlugin.js"></script>

    <script type="text/javascript">
         document.addEventListener("deviceready", onDeviceReady, false);

        function onDeviceReady() {
             console.log("Cordova Ready...");
        }

        function requestRewardAd() {
             console.log("Load Reward Ad Start");

            callbackFunction = RewardAdEvent;

            loadRewardAdFromSDK(“YOUR_API_KEY”);
        }

        function showRewardDialog() {
             if (REWARD_AD_LOADED == true) {
                 var dialog = document.getElementById('premodal');

                document.getElementById('yes').onclick = function() {
                     dialog.close();
                     showRewardAd();
                 };

                document.getElementById('no').onclick = function() {
                     dialog.close();
                 };

                dialog.showModal();
             } else {
                 alert("Reward Ad Not Loaded.");
             }
        }

        function showRewardAd() {
             console.log("Show Reward Ad Start");

             //Parma 1 : Secret Key (Get it from Vdopia Portal : Required if server-to-server callback enabled)

             //Parma 2 : User name of the App user

             //Param 3 : Reward Name or measure

             //Param 4 : Reward Amount or quantity
             showRewardAdFromSDK("qj5ebyZ0F0vzW6yg", "CordovaUser", "coin", "30");
         }

        function rewardAdCompleted() {
             var dialog = document.getElementById('postmodal');
             setTimeout(function(){ dialog.close(); }, 3000);
             dialog.show();
        }

        function RewardAdEvent(message) {
             console.log("Reward Ad Event ::: " + message);

            if (message === "onRewardedVideoCompleted") {
                 rewardAdCompleted();
            } else if (message == "onRewardedVideoShown") {

               //OPTIONAL: We recommend pre-fetching the next reward ad while
               //the current ad is being shown. This increases the chances your next 
               //ad request will be ready immediately. 
  
               prefetchRewardAdFromSDK("YOUR_API_KEY");

            }
        }
     </script>
 </head>

<body>
 <div class="navbar">
     <div class="button button-left"><a href="javascript:history.back()">
         <img src="img/arrow_green.png"/></a></div>
     <div class="nav_title">Reward</div>
     <div class="button button-right"><a href="setting.html"><img src="img/gear_green.png"/></a>
     </div>
 </div>

<dialog id="premodal" class="centerDialog">
     <b>Earn 30 Virtual Coins ?</b>
     <p>Watch a Video and earn 30 Virtual Coins!</p>
     <button id="no">No Thanks</button>
     <br/><br/>
     <button id="yes">Watch Video</button>
 </dialog>

<dialog id="postmodal" class="centerDialog">
     <p>Thanks! You have earned 30 virtual coins.</p>
</dialog>

<br/><br/><br/>
<div class="centerDiv">
     <button onclick="requestRewardAd()">Request Reward Ad</button>
     <br/><br/>
     <button onclick="showRewardDialog()">Show Reward Ad</button>
</div>
</body>
</html>

The above sample shows how to load the Reward Ad and show the Reward Ad.

While showing the Reward Ad there are 4 parameters explained in comments.

Premodal and Postmodal popup should be created as per the publisher requirement and design.

Below is the list of events message for Reward Ad:
onRewardedVideoLoaded

onRewardedVideoFailed

onRewardedVideoShown

onRewardedVideoShownError

onRewardedVideoDismissed

onRewardedVideoCompleted
• Targeting Parameters:

Below is the method to set the Ad targeting parameters for better Ad Target

//Param 1 : Age

//Param 2 : BirthDate (dd/MM/yyyy)

//Param 3 : Gender (m/f/u)

//Param 4 : Marital Status (single/married/unknown)

//Param 5 : Ethinicty (example : Africans/Asian/Russians)

//Param 6 : DMA Code (in String format)

//Param 7 : 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

setAdRequestUserParams("23", "23/11/1990", "m", "single", "Asian", "999", "123123", "321321", "28.70", "77.10");

//Param 1 : App Name

//Param 2 : Publisher Name

//Param 3 : App Domain

//Param 4 : Publisher Domain

//Param 5 : PlayStore URL of the App

//Param 6 : Ad Category

setAdRequestAppParams("CordovaDemo", "Vdopia", "cordova-demo.com", "vdopia.com", "", "movie");

//Param 1 : boolean : true if test mode enabled else false

//Param 2 : Hash ID (For Facebook/Google Partner Test Ad, you can get from ADB Logcat)

//setTestModeEnabled(true, "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");

 

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 rewardAdCompleted() {
    // Handle your rewarding here
}

 

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