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.
Before you begin the integration process, make sure you have the following requirements in place:
- Android Build Support Tools: You must install Android Studio
Here's a quick walkthrough from installation to showing Offers to get you started on the fastest route.
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.
Depending on your app setup, please follow either:
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.
Steps to build and run the demo app:
- Unzip the downloaded file.
- Open the AdsPostXDemo folder with Android Studio.
- Wait until the Gradle sync is completed.
- Depending on whether you have an Android device connected to the system or not, Android Studio will give you options to run the app.
- Select Run to run the app on the connected device/emulator.
Obtain the latest version of the AdsPostX Android SDK using the link provided below.
- Unzip the downloaded zip file.
- Extract the contents of the zip file into a directory.
- The extracted directory contains theadspostx-release.aarframework.
- Then, follow the instructions provided below to integrate AdsPostX with your mobile application.
This guide assumes that you are familiar with Gradle and with installing a plugin for Android development.
- In the directory where the files were extracted, locate the adspostx-release.aar file.
- Open your Android project and view it in Project mode.
3. Drag and drop the adspostx-release.aar file inside the libs folder.
4. From the Android Studio menu, go to File -> Project Structure. Select Dependencies -> app.
5. Press the + button, and then select JAR/AAR Dependency.
6. Enter the path to the added adspostx-release.aar framework, then press OK and Apply.
7. Wait for Gradle to finish syncing.
Open your application's app-level Gradle file, and add the following dependency in the dependencies section.
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!
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:
3. Open the app-level build.gradle file.
- Add the following dependencies:
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!
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.
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.
Import AdsPostX in your Android Project.
Here is an example of a fully-formed call using the getOffers method:
where Offer is defined as:
SDK ID as provided
dictionary [String: Any]
User payload parameters and other filters/options
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.
contains offers info.
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.
A successful call to getOffers would return a JSONObject as follows:
A failed call to getOffers would return an error response similar to the following:
Integration consists of three steps.
- Initializing SDK
- Loading Offers
- Displaying Offers
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.*
SDK ID as provided.
completion handler/lambda required
A call is returned on init function with status.
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.
client application context.
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 block/ lambda required
A callback will be fired on load in the completion handler(lambda).
Currently, the following attributes are supported:
Attribute Data Type
Load() with Attributes:
Load() without Attributes:
Once init and load calls are successful, call showOffers to display offers in your app.
can be either FULLSCREEN or POPUP
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.
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%).
Lambda of type (Unit) -> Unit
A callback will be fired in this lambda function before while offers.
Lambda of type (Exception) -> Unit
A callback will be fired in this lambda function when there is an exception while showing offers.
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.
Showing offers along with margins and transparency:
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.
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.
If you're running into any issues while going through the integration process, feel free to contact us at email@example.com.