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.
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.
Then select the copied libs folder as additional libraries path in B4A using Configure Paths under Tools menu.
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
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.
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.
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:
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.
|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.
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.
Show video in portrait orientation
Show video in landscape orientation
Unlocked screen orientation
Show video in reversed portrait orientation
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.
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.