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

Tapsell SDK Integration Guide for B4A

(Version3.0.5)

 

Project Setup

These are a few quick steps that must be taken prior to integrating Tapsell ads in your application.

 

Step 1: Download Tapsell SDK

First of all, download the SDK from the following URL and unzip the file:

 

Step 2: Add Tapsell SDK to B4A Libraries

Copy TapsellSDK.xml and TapsellSDK.jar files to Libraries Folder in B4A installation path. Open your B4A project, right click in Libraries Manager section and refresh the list. Select Tapsell SDK library from the list and add it to your project.

B4A

 

Step 3: Add dependencies

If you have defined a path for additional libraries in your application, copy the jar files located in libs folder of Tapsell SDK to the path defined in Tools->Configure Paths->Additional Libraries and move to next step.

Otherwise, copy libs folder in your B4A project path next to Files and Objects folders.

B4A

Then select the copied libs folder as additional libraries path in B4A using Configure Paths under Tools menu.

B4A

 

Step 4: Configure Activity Attributes

Copy the following lines to Activity Attributes region in your main project file.

#Region Activity Attributes
    ...
    #AdditionalJar : gson-2.8.0.jar
    #AdditionalJar : tapsell-b4a-3.0.5.jar
#End Region

 

B4A

 

Step 5: Update Manifest

Open Manifest Editor which is located under Project menu and add following lines to your app’s manifest.

AddManifestText(
    …
    <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"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>)
    …
'End of default text.
AddApplicationText(
    <!-- Required Activity -->
    <activity
        android:name="ir.tapsell.sdk.TapsellAdActivity"
        android:configChanges="keyboardHidden|orientation|screenSize"/>
    )

In above code, ACCESS_COARSE_LOCATION permission is optional. However, adding this line would help Tapsell to show targeted ads to your users.

B4A

Now you are ready to use Tapsell Ads SDK in your B4A Project!

 

 

Using Tapsell SDK in your app

 

Step 1: 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 2: Import and Initialize Tapsell

In order to use Tapsell SDK, you need to create and Instance of ‘Tapsell’ class in your application. To do so, add the following piece of code to Global subroutine of your main project file.

Sub Globals
 Private tapsell As Tapsell
End Sub

 

Then add the following line of code in your Activity_Create subroutine.

tapsell.initialize(appKey)

AppKey argument is the key provided to you by tapsell administration panel in previous step.

 

Step 3: 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 request an Ad in your application, use the following method:

tapsell.requestAd(zoneId,isCached)

 

In this function, zoneId argument shows the zone in which you with to show the ad. In order to use the default zone created by Tapsell, you can pass an empty string for this argument.

The second argument, isCached, indicates whether the ad should be cached before being shown to the user or not (stream mode).

The result of your request is delivered as an event to subroutines in your app.  If a suitable ad was found, a subroutine named Tapsell_onAdAvailable will be called providing you and advertisement id which you can use to show the ad. In the next step, subroutines used by Tapsell SDK are listed with description.

 

Step 4: Add Required Subroutines

Add following lines to your main file:

Sub Tapsell_onAdAvailable (zoneId As String, adId As String)
    ' ad is available to show, store adId to show it later
    ad = adId
End Sub

Sub Tapsell_onNoAdAvailable (zoneId As String)
    ' No ad available now
End Sub

Sub Tapsell_onNoNetwork (zoneId As String)
    ' No network
End Sub

Sub Tapsell_onError (zoneId As String, error As String)
    ' Encountered and error while connecting to tapsell
End Sub

Sub Tapsell_onExpiring (zoneId As String, adId As String)
    ' The stored ad with given adId is expiring and cannot be shown anymore
    ad = Null
End Sub

Description of required subroutines is given in Table 1.

Table 1 Subroutines used by Tapsell SDK to respond an ad request
Function Description
Tapsell_onError (String) Called when an error is occurred during sending request to the server.
Tapsell_onAdAvailable (String, String) Called when the ad is ready to be shown. You should store the returned id in order to show the ad later.
Tapsell_onNoAdAvailable (String) Called when no suitable ad was found.
Tapsell_onNoNetwork (String) Called when device is not connected to internet.
Tapsell_onExpiring (String, String) 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

Use the following method to show an ad. Please note that it can be called only once for each adId.

tapsell.showAd(adId,back_disabled,immersive_mode,rotation_mode)

 

Argument adId is the id of the ad which is given to you in onAdAvailable subroutine.

‘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

 

Step 6: Get Results

The result of showing the ad is delivered to Tapsell_onAdShowFinished subroutine. Therefore, you need to add this subroutine to your project if you are going to use rewarded video ads.

Sub Tapsell_onAdShowFinished (zoneId As String, adId As String, completed As Boolean, rewarded As Boolean)
    ' showing ad was finished
End Sub

In the returned result, zoneId and adId represent the id of the ad and associated zone for which the ad was requested. 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