1. Home
  2. Publishers
  3. Using Tapsell Ads in Unity Project

Using Tapsell Ads in Unity Project

This document contains step by step instructions for integrating Tapsell video ads in your application.

Step 1: Download Tapsell SDK

Download our SDK from the following link and import it in your project:

Step 2: Get App-Key

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

To use tapsell SDK, you must add the namespace.

using TapsellSDK;

The first step is to add a function that will initialize Tapsell SDK. In your C# script, add the below code:

Tapsell.initialize(appKey);

appKey argument is the key you copied from Tapsell website.

Now add these permissions to your Manifest file:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" /><!--optional-->
<uses-permission android:name="android.permission.VIBRATE" /><!--optional-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/><!--optional-->

And this line inside <application> scope:

<activity android:name="ir.tapsell.sdk.TapsellAdActivity" android:configChanges="keyboardHidden|orientation|screenSize" /> 

Step 4: Requesting an Ad

Showing an ad in application may be done in two ways: Caching or streaming the video. Moreover, you can show Ads in different zones inside your application.
To request an ad in your application, use the following function:

Tapsell.requestAd(zoneId, cached, Action<TapsellAd> onAdAvailableAction,
    Action<string> onNoAdAvailableAction, Action<TapsellError> onErrorAction,
    Action<string> onNoNetworkAction, Action<TapsellAd> onExpiringAction);

In this function, zoneId argument indicates the zone in which you with to show the ad. You can get the zoneId from your app page in dashboard. Note that you should not 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 actions. A sample implementation of required actions is given below.

Tapsell.requestAd(zoneId, cached, 
    (TapsellAd result) => {
       // onAdAvailable
       Debug.Log("Action: onAdAvailable");
       TapsellAd ad = result; // store this to show the ad later
    },

    (string zoneId) => {
        // onNoAdAvailable
        Debug.Log("No Ad Available");
    },

    (TapsellError error) => {
        // onError
        Debug.Log(error.error);
    },

    (string zoneId) => {
        // onNoNetwork
        Debug.Log("No Network");
    },

    (TapsellAd result) => {
        // onExpiring
        Debug.Log("Expiring");
        // this ad is expired, you must download a new ad for this zone
    }
);

Description about the actions for requesting an ad is given in Table 1.

Table 1 Methods of ad request listener interface
Function Description
onErrorAction(TapsellError) Called when an error is occurred during sending request to the server.
onAdAvailableAction(TapsellAd) Called when the ad is available and ready to be shown. You should store the returned ad id in order to show it later.
onNoAdAvailableAction (string) Called when no suitable ad was found.
onNoNetworkAction (string) Called when device is not connected to internet.
onExpiring(TapsellAd) 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.s

 

Step 5: Show the Ad

To show an ad, you can call the following function with stored id of the ad.

Tapsell.showAd(ad, showOptions);

Argument ad is the id of the ad which is included in TapsellAd item returned in onAdAvailable  action. Note that this function may be called once for each ad item.
The showOptions argument in code above is an object of type TapsellShowOptions class. The field variables of this class are described in Table 2.

Table 2 Variables of TapsellShowOptions object
Variable (type) Description
backDisabled (bool)
‘True’ if the user is allowed to use ‘Back’ button to stop playing the video, ‘false’ otherwise.
immmersiveMode (bool)
True’ if the ad must be shown in immersive mode. (Is applied in devices running Android 4.4 KitKat and above)
rotationMode (int)
The orientation of devices when showing the ad. Can have one of the following values:
ROTATION_LOCKED_PORTRAIT,
ROTATION_LOCKED_LANDSCAPE,
ROTATION_UNLOCKED,
ROTATION_LOCKED_REVERSED_PORTRAIT,
ROTATION_LOCKED_REVERSED_LANDSCAPE

An implementation for showing ad is given below.

TapsellShowOptions options = new TapsellShowOptions ();
options.backDisabled = false;
options.immersiveMode = false;
options.rotationMode = TapsellShowOptions.ROTATION_UNLOCKED;
options.showDialog = false;
Tapsell.showAd(ad, options);

 

Step 6: Get Results of Showing Ad

If you use rewarded video ads in your application and need to know whether the user has watched the video completely, you should use the following method to pass an action to the SDK.

Tapsell.setRewardListener( (TapsellAdFinishedResult result) => 
	{
		// you may give rewards to user if result.completed and
		// result.rewarded are both true
	}
);

Result for showing the ad is returned to onAdShowFinished action. After showing the ad, the onAdShowFinished action is called with the result as an object of TapsellAdFinishedResult . When the shown ad is rewarded, the ‘rewarded’ variable of the result will be true. You should give the in-app rewards (credit, coin, gem, etc.) to the user when both  completed and  rewarded variables in the result have 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.

 

Next: Implementing Native Banner Ads in Unity project (Android)

Was this article helpful?

Related Articles