1. Home
  2. Publishers
  3. Tapsell SDK Integration Guide for Cordova

Tapsell SDK Integration Guide for Cordova

(Version 3.0.25)

Step 1: Add Tapsell plugin to your Cordova project

First of all, open command prompt and navigate to your Cordova project folder. Then execute the below command:

 cordova plugin add tapsell-v3-cordova-plugin

Now Tapsell plugin is added to your project.

 

Step 2: Get AppKey

Log in your Tapsell account and get a new tapsell key by creating a new application. This key is needed for using tapsell APIs.

 

Step 3: Initialize Tapsell

Use the key generated for your app to initialize tapsell. To use tapsell, you must first call the below method in your onDeviceReady event.

tapsell.initialize(appKey);

AppKey argument is Tapsell key provided to you in administration panel.

 

Step 4: Request an Ad

Showing an Ad in application may be done in two ways. Caching or Streaming the video. Also you can show Ads in different “zones” inside your application.
To show an Ad in your application, use the following function:

tapsell.requestAd(zoneId, cached, function(result){
    if(result['action']=='onAdAvailable')
    { 
        zoneId = result['zoneId']; 
        adId = result['adId']; // store this to show the ad later
    }
    else if( result['action']=='onNoAdAvailable' )
    {
        zoneId = result['zoneId'];
    }
    else if( result['action']=='onNoNetwork' )
    {
        zoneId = result['zoneId'];
    }
    else if( result['action']=='onError' )
    {
        zoneId = result['zoneId'];
        error = result['error']; // description of error
    }
    else if(result['action']=='onExpiring')
    { 
        zoneId = result['zoneId'];
        adId = result['adId'];
        // indicates that this ad cannot be shown anymore, you should 
        // request a new add
    } 
});

In this function, “zoneId” argument indicates the zone in which you with to show the ad. For using the default zone created by Tapsell, you can pass a null value for this argument.

The second argument, “cached”, is a Boolean indicating whether the ad should be cached before showing or not (streamed).

The result of the request is returned to the the 3rd argument, named callback. As demonstrated in code above, you should store adId for future use if the returned action in callback is onAdAvailable. If the onExpiring action is called, it means that the stored ad is expired and cannot be shown anymore.

Table 1 contains different possible values for action description of each value.

 

Table 1. Possible action values and description
Action (other parameters) Description
onError (zoneId, error) Called when an error is occurred during sending request to the server.
onAdAvailable (zoneId, adId) Called when the ad is available and ready to be shown. You should store the returned ad id in order to show it later.
onNoAdAvailable (zoneId) Called when no suitable ad was found.
onNoNetwork (zoneId) Called when device is not connected to internet.
onExpiring (zoneId, adId) Called when the ad is expired. Ads have an expiration time and when that time is passed, that ad becomes invalid and cannot be shown. In this case, you might consider requesting a new ad.

Step 5: Show the Ad

To show an ad, you need the ad id which is given to you in previous step. Use the below method to show an ad (This function can be called only once for each id) :

tapsell.showAd(adId, disable_back, immersive_mode, rotation_mode , function (result){
    if(result['action']=='onAdShowFinished')
    {
        console.log('showing ad was finished');
        zoneId = result['zoneId'];
        adId = result['adId'];
        completed = result['completed'];
        rewarded = result['rewarded'];
    }
});

The 1st argument adId is the id of the ad which is returned in previous step.

disable_back and immersive_mode are Boolean arguments which indicate whether the back button should be disabled while showing rewarded videos and the video should be shown in Immersive Mode.

The 4th argument, rotation_mode is used to determine the orientation of device while showing the ad. Table 2 includes valid values for this argument and description of each value.

 

Table 2. Accepted values for rotation_mode
Value Description
tapsell_rotation_locked_portrait
Show video in portrait orientation
tapsell_rotation_locked_landscape
Show video in landscape orientation
tapsell_rotation_unlocked Unlocked screen orientation
tapsell_rotation_locked_reversed_portrait
Show video in reversed portrait orientation
tapsell_rotation_locked_reversed_landscape Show video in reversed landscape orientation

The last argument in showAd function is the callback which receives the result of showing ad. ZoneId and adId parameters represent the id of shown ad and associated zone. The next two arguments, rewarded and completed indicate whether the type of shown ad is rewarded and whether the user has watched the video completely. You should give the in-app rewards (credit, coin, gem, etc.) to the user when both completed and rewarded variables in the result are true.

 

 

Sample Project

A sample project is located in the following repository in case more information about the SDK is needed.

 

 

 

Please let us know whether this document was helpful and what complications you faced while using Tapsell Android SDK.

Was this article helpful?

Related Articles