Website logo
Dashboard
⌘K
🚀Integration Guide Overview
JS SDK (for Websites)
Presentation Options
Google Tag Manager (GTM)
Google Ad Manager (GAM)
Mobile SDK
iOS SDK
Android SDK
React Native SDK
Flutter SDK
Using macros
Passing payload values
Shopify
API
Native Ads API
Reporting API
Settings API
Errors
Postbacks
LoyaltyBoost (Rewarded Campaigns)
Perkswall
Frequently Asked Questions
Adding AdsPostX to your page
Offerwall
Docs powered by Archbee
Mobile SDK

Android SDK

Introduction

Welcome to the guide on integrating AdsPostX into your Android application. This comprehensive documentation is designed to assist developers in seamlessly incorporating AdsPostX Offers into their Android Apps. Whether you're looking to monetize your app or enhance user engagement, AdsPostX provides a powerful solution. Before getting started, please ensure that you already have an account with AdsPostX. If you don't have an account yet, you can easily create a new one now. Once you have your account credentials, you can proceed with the integration process outlined in this guide. Let's dive in and explore the features and functionalities of the AdsPostX Android SDK to unlock the full potential of AdsPostX within your Android Application.

Requirements

Before you begin the integration process, make sure you have the following requirements in place:

  1. Android Build Support Tools: You must install Android Studio

Quick Walkthrough

Here's a quick walkthrough from installation to showing Offers to get you started on the fastest route. 

<div style="position: relative; padding-bottom: calc(71.45028142589118% + 44px); height: 0;"><iframe src="https://app.supademo.com/embed/clkqz2b05o4hfzg70kxsbw7t2" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>


Minimum Deployment Target

Ensure that your Android Project meets the minimum deployment target requirements:

The minSdk for your Android Project should be 24.

In your Android project. Open app-level build.gradle file.

Change the value of minSdk to 24 inside the android -> defaultConfig section.

Kotlin
android {

...
    defaultConfig {
        ...
        minSdk 24
        ...
    }
...
}


Latest version

version

1.0.10

Installation

Depending on your app setup, please follow either:

Manual Installation

Using JitPack

Manual Installation

Download and build the AdsPostX Android Demo App

Before integrating AdsPostX into your Android app, we recommend that you download and build our demo app in order to familiarize yourself with the code and implementation methods.

Download Android SDK Demo App


Steps to build and run the demo app:

  1. Unzip the downloaded file.
  2. Open the AdsPostXDemo folder with Android Studio.
  3. Wait until the Gradle sync is completed.
  4. Depending on whether you have an Android device connected to the system or not, Android Studio will give you options to run the app.
  5. Select Run to run the app on the connected device/emulator.

Download the AdsPostX Android SDK

Obtain the latest version of the AdsPostX Android SDK using the link provided below.

Download AdsPostX Android SDK

  1. Unzip the downloaded zip file.
  2. Extract the contents of the zip file into a directory.
  3. The extracted directory contains theadspostx-release.aarframework.
  4. Then, follow the instructions provided below to integrate AdsPostX with your mobile application.

Include the SDK in your app

Before you begin

This guide assumes that you are familiar with Gradle and with installing a plugin for Android development.

Adding .aar

  1. In the directory where the files were extracted, locate the adspostx-release.aar file.
  2. Open your Android project and view it in Project mode.
Document image


3. Drag and drop the adspostx-release.aar file inside the libs folder.

Document image


4. From the Android Studio menu, go to File -> Project Structure. Select Dependencies -> app.

Document image


5. Press the + button, and then select JAR/AAR Dependency.

Document image


6. Enter the path to the added adspostx-release.aar framework, then press OK and Apply.

Document image


7. Wait for Gradle to finish syncing.

Adding dependencies

Open your application's app-level Gradle file, and add the following dependency in the dependencies section.

Kotlin

implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.2"
implementation "com.google.android.material:material:1.8.0"


9. Select Sync Now to sync the Gradle.

Thats it! You have now installed the Android SDK with all the dependencies required for your project to support AdsPostX!

Using JitPack

1. To install AdsPostX via Jitpack, first open settings.gradle in your Android client app.

2. In PluginManagement -> Repositories section and also in dependencyResolutionManagement -> repositories add:

maven { url 'https://jitpack.io' }

3. Open the app-level build.gradle file.

Adding dependencies

  1. Add the following dependencies:
Kotlin

implementation 'com.github.AdsPostX:adspostx-android:1.0.10' // replace it with latest sdk version.
implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.2" //peer dependency for adspostx
implementation "com.google.android.material:material:1.8.0" //peer dependency for adspostx


2. Perform gradle sync or click on sync project with gradle files, and wait for the process to finish.

Thats it! You have now installed the Android SDK with all the dependencies required for your project to support AdsPostX using JitPack!

Integration

There are two ways to integrate AdsPostX into your Android App.

Native Ads API Integration Native Ads API provides a highly flexible implementation method. With Native Ads API, you can retrieve Offers in a JSON response and then parse and display them according to your specific requirements. The JSON response contains individual fragments that make up an Offer, giving you full control over how the ad is rendered. This method allows for deep customization and styling to seamlessly blend the Offers into your app's UI.

Standard Integration If you prefer a quick and straightforward way to display AdsPostX Offers without the need for extensive customization, the Standard integration is a suitable option. It offers a pre-built modal box that can be easily integrated into your Android App. While it may not provide the same level of customization as Native Ads, the Standard integration does allow basic theming options that can be controlled through the AdsPostX dashboard. This option is ideal for those who prioritize simplicity and quick implementation.

Native Ads API Integration

Once you've installed the AdsPostX Android SDK using the step(s) above, you can simply use the getOffers call to retrieve Offers. You will need you SDK ID in order to do so.

Usage

Import AdsPostX in your Android Project.

Kotlin
import com.adspostx.sdk.*


Here is an example of a fully-formed call using the getOffers method:

Kotlin
private var parameters: MutableMap<String, Any>? = null

parameters?.set("country", "USA")
parameters?.set("firstname", "dev")
parameters?.set("creative", "1")

AdsPostX.getOffers(sdkId, parameters, this) { result ->
  result.onSuccess {
    val gson = Gson()
    val dataJson = it.getJSONObject("data")
    val offersJsonArray = dataJson.getJSONArray("offers")

    val listType = object : TypeToken<List<Offer>>() {}.type
    offers = gson.fromJson(offersJsonArray.toString(), listType)
  }
  result.onFailure { // it: Throwable error
    // handle error
  }
}


where Offer is defined as:

Kotlin
data class Offer(
    val id: Int,
    val title: String?,
    val description: String?,
    val click_url: String?,
    val image: String?,
    val pixel: String?,
    val cta_yes: String?,
    val cta_no: String?,
)


where

Parameter Name

Parameter Type

Optional/Required

Description

sdkId

string

required

SDK ID as provided

parameters

dictionary [String: Any]

optional

User payload parameters and other filters/options

context

ApplicationContext

required

client application context.

It returns a Result object. When the successful call has been made, it returns JSONObject. or In case of failure, it returns error info.

Parameter Name

Data Type

Description

json

JSONObject

contains offers info.

error

Exception

contains error info

The getOffers method is effectively a wrapper around the AdsPostX Native Ads API which you can learn more about here. The payload and options values can be passed through and used interchangeably with the Native Ads API.

In the example above, the parameters parameter is passing user payload information including country and firstname. The payload parameter also includes a creatives: 1 option to instruct AdsPostX to only return Offers that have at least one creative.

The getOffers response object will contain Offers if Offers are available and can then be parsed to display them using the Offers fragments provided.

To accurately report events such as impressions, opt-outs, etc, each Offer contains beacon URL to fire based on the nature of the event. For impressions, use the pixel attribute. For other events, refer to the beacons attribute to handle. For example, if the user presses "No thanks" on the offer, fire the no_thanks_click beacon URL.

getOffers Response Example

Success

A successful call to getOffers would return a JSONObject as follows:

JSON
{
  "data": {
    "offers": [
      {
        "id": 4053,
        "mini_text_html": "<p>Sample Mini Text here</p>",
        "description": "<p>Upgrade your headwear game by grabbing this Texas Rangers Chrome 59FIFTY Fitted Hat from New Era. Highlighting your loyalty to the team will be super easy thanks to the distinctive Texas Rangers graphics embroidered on the crown.</p><p>Upgrade your headwear game Now. Don't just wait. </p>",
        "creatives": [
          {
            "url": "https://adpx.b-cdn.net/campaigns/1330/2c893d4226891cc160dd6658a660bbeb.png",
            "type": "png",
            "width": 900,
            "id": 1009,
            "is_primary": true,
            "aspect_ratio": 1,
            "height": 900
          },
          {
            "url": "https://adpx.b-cdn.net/campaigns/1330/e4ea32bf3c8f2c6434d59df46a986dc1/avif",
            "type": "heif",
            "width": 900,
            "id": 1010,
            "is_primary": false,
            "aspect_ratio": 1,
            "height": 900
          }
        ],
        "image": "https://adpx.b-cdn.net/campaigns/1330/2c893d4226891cc160dd6658a660bbeb.png",
        "adv_pixel_url": "",
        "cta_no": "No, Thanks",
        "title": "Texas Rangers New Era Chrome 59FIFTY Fitted Hat - Stone/Black",
        "beacons": {
          "no_thanks_click": "https://track.adspostx.com/event/record/no_thanks_click?oid=4053&cid=1330&pid=800&sess_id=e7ff9c17a762751520be3315ba22fe9e7be8323f",
          "close": "https://track.adspostx.com/event/record/close?oid=4053&cid=1330&pid=800&sess_id=e7ff9c17a762751520be3315ba22fe9e7be8323f"
        },
        "click_url": "https://track.adspostx.com/sdk/offer-click?o_id=4053&c_id=1330&p_id=800&sess_id=e7ff9c17a762751520be3315ba22fe9e7be8323f",
        "useraction_url": "https://www.adspostx.com/get-started?click={click_id}",
        "useraction_cta": "Buy Now",
        "cta_yes": "Yes, please",
        "pixel": "https://track.adspostx.com/sdk/v2/impression/p.png?o_id=4053&c_id=1330&p_id=800&sess_id=e7ff9c17a762751520be3315ba22fe9e7be8323f&cbuster={CBUSTER}"
      }
    ],
    "styles": {    //styles settings for the template associated with the account used by the Standard Integration. Can be ignored.
      "offerText": {
        "fontSize": 14,
        "font": null,
        "buttonYes": {
          "hover": "#1A56DB",
          "stroke": "#1C64F2",
          "background": "#1C64F2",
          "color": "#ffffff"
        },
        "buttonNo": {
          "hover": "#E5E7EB",
          "stroke": "#9CA3AF",
          "background": "#ffffff",
          "color": "#6B7280"
        },
        "textColor": "#000"
      },
      "footer": {
        "publisher_name": "Ansh LLC",
        "privacy": "https://www.adspostx.com/privacy-policy",
        "text": "Powered by AdsPostX",
        "publisher_privacy_policy": "https://www.enefits.co/privacy",
        "disclaimer": ""
      },
      "header": {
        "text": "Your order is complete",
        "lead_in_text_color": "#000000",
        "lead_in_text": "Here are some offers from brands you love!",
        "textColor": "#ffffff",
        "fontSize": 16,
        "background": "#1A56DB"
      },
      "settings": {
        "screen_margin": 0,
        "darken_bg_non_centered": false,
        "show_disclaimer": false,
        "ad_position": "center",
        "ad_animation": "bottom-top",
        "enable_vertical_offset": false,
        "button_order": "neg_first",
        "delay": 0,
        "mobile_vertical_offset": null,
        "darken_bg": true,
        "fixed_progress_bar": false
      },
      "popup": {
        "shadow": "#8f8f8f",
        "borderRadius": {
          "bottom_right": "5",
          "top_right": "5",
          "top_left": "5",
          "bottom_left": "5"
        },
        "background": "#ffffff",
        "lightBox": "#000"
      }
    },
    "count": 1    //number of Offers returned by the getOffers method determined in the AdsPOstX dashboard via Settings/Behaviour.
  }
}


Failure

A failed call to getOffers would return an error response similar to the following:

Kotlin
org.json.JSONException: End of input at character 0 of ...


Standard Integration

Integration consists of three steps.

  1. Initializing SDK
  2. Loading Offers
  3. Displaying Offers

Initializing the SDK

Include the AdsPostX initialization code anywhere in the app, but make sure to call it before loading and showing offers.

Also, make sure to import com.adspostx.sdk.*

Kotlin

 fun init(sdkId: String,
             completion: (status: Boolean, error: Exception?) -> Unit)


where

Parameter Name

Parameter Type

Description

sdkId

String required

SDK ID as provided.

completion

completion handler/lambda required

A call is returned on init function with status.

Example:

Kotlin
// values used here are just for demo purpose, use actual values when you are integrating SDK.

 AdsPostX.init("25") { status, error ->
    if (status) {
        println("SDK initialized successfully.")
    } else {
        if (error != null) {
            println(error.message)
        } else {
            println("Unknown error")
        }
    }
}


Loading Offers

Once the SDK is initialized successfully, you can call the load function to load Offers.

The load function must be called at least once before showing Offers.

Kotlin
fun load(applicationContext: Context,
                   attributes: Map<String, Any>? = null,
                   completion: (status: Boolean, error: Exception?) -> Unit)


where

Parameter Name

Parameter Type

Description

applicationContext

Context

client application context.

attributes

Map optional

attributes and their values that you would like to send to AdsPostX

Note: All attributes must be passed based on the supported list below.

completion

Completion block/ lambda required

A callback will be fired on load in the completion handler(lambda).

Currently, the following attributes are supported:

Attribute Name

Attribute Data Type

email

String

firstname

String

lastname

String

mobile

String

confirmationref

String

amount

double

currency

String

paymentType

String

ccbin

String

language

String

country

String

zipcode

String

orderid

String

offerid

String

subid

String

Example:

Load() with Attributes:

Kotlin
// values used here are just for demo purpose, use actual values when you are integrating SDK.

var attribute = mutableMapOf<String , Any>()
attribute["email"] = "john@gmail.com"
attribute["firstname"] = "John"
attribute["lastname"] = "Dev"
attribute["country"] = "USA"
attribute["amount"] = 500.0

AdsPostX.load(applicationContext, attribute) { status, error ->
    if (status) {
        println("Offers loaded Successfully.")
    } else {
        if (error != null) {
            println(error?.message)
        } else {
            println("Unknown Error!")
        }
    }
}


Load() without Attributes:

Kotlin
// values used here are just for demo purpose, use actual values when you are integrating SDK.

AdsPostX.load(applicationContext) { status, error ->
    if (status) {
        println("Offers loaded Successfully.")
    } else {
        if (error != null) {
            println(error?.message)
        } else {
            println("Unknown Error!")
        }
    }
}


Displaying offers

Once init and load calls are successful, call showOffers to display offers in your app.

Kotlin
fun showOffers(presentationStyle: AdsPostXPresentationStyle,
                   isTransparent: Boolean = true,
                   margin: Margin = Margin(5u,5u,5u,5u),
                   onShow:(Unit) -> Unit,
                   onError:(Exception) -> Unit,
                   onDismiss:(Unit) -> Unit)


where

Parameter Name

Parameter Type

Description

presentationStyle

AdsPostXPresentationStyle required

can be either FULLSCREEN or POPUP

isTransparent

Boolean optional

can be either true or false

the default value is true



If isTransparent = true, the background will be transparent.



If isTransparent = false, the background will be non-transparent.

margins

Margin(UInt, UInt, UInt, UInt) optional

1st parameter: describes top margin in %.

2nd parameter: describes bottom margin in %.

3rd parameter: describes left margin in %.

4th parameter: describes right margin in %.

margin values must be >= 0 and <= 15 Default margin values for top margin, bottom margin, left margin, right margin is 5 (ie. 5%).

onShow

Lambda of type (Unit) -> Unit

A callback will be fired in this lambda function before while offers.

onError

Lambda of type (Exception) -> Unit

A callback will be fired in this lambda function when there is an exception while showing offers.

onDismiss

Lambda of type (Unit) -> Unit)

A callback will be fired in this lambda after the offer modal is dismissed.

The margin will be calculated based on the orientation. If the device is in landscape orientation, the margin will be calculated considering the device height. If the device is in portrait orientation, the margin will be calculated considering the device width.

If margin value is > 15 then it will consider only 15.

After displaying offers, the load function must be called again before displaying offers again.

Example:

Showing offers along with margins and transparency:

Kotlin
// values used here are just for demo purpose, use actual values when you are integrating SDK.

AdsPostX.showOffers(
    AdsPostXPresentationStyle.POPUP,
    true,
    margin = Margin(5u,5u,5u,5u),
    onShow = {
        println("On show")
    }, 
    onError = {
        println(it)
    },
    onDismiss = {
        println("Dismiss")
    })


Set Environment

The default value for the environment is LIVE.

We recommend using the TEST environment only during development and not in production.

Make sure to call setEnvironment method before the init() call.

Kotlin
AdsPostX.setEnvironment(AdsPostxEnvironment.LIVE)

// OR

AdsPostX.setEnvironment(AdsPostxEnvironment.TEST)


Set Debug Log

By Default, DebugLog is disabled.

Enabling Debug Log will give you more debug information related to offers.

We recommend enabling logs only in development, not in production.

Make sure to call setDebugLog() method before init() call.

Kotlin
AdsPostX.setDebugLog(true)

// OR

AdsPostX.setDebugLog(false)


Need Help?

If you're running into any issues while going through the integration process, feel free to contact us at help@adspostx.com.

PREVIOUS
iOS SDK
NEXT
React Native SDK
Docs powered by Archbee
TABLE OF CONTENTS
Introduction
Requirements
Quick Walkthrough
Minimum Deployment Target
Latest version
Installation
Manual Installation
Download and build the AdsPostX Android Demo App
Download the AdsPostX Android SDK
Include the SDK in your app
Before you begin
Adding .aar
Adding dependencies
Using JitPack
Adding dependencies
Integration
Native Ads API Integration
Usage
getOffers Response Example
Standard Integration
Initializing the SDK
Loading Offers
Displaying offers
Set Environment
Set Debug Log
Need Help?
Docs powered by Archbee