Native Ads API
he AdsPostX Native Ads API is a powerful platform that allows publishers to easily integrate Offers within their app or website using any language that supports the ability to make RESTful calls.
The typical flow to generate and serve Offers is as follows:
- Make a Fetch Ads API call to AdsPostX to retrieve Offers (see below for information)
- Parse the response and display Offers in the desired fashion
- Ensure that beacon URLs fire on sequence and Offer impression loads.
Once you generate an API Key in Step 1 above, try the Native Ads API by visiting our Native Ads API Tester.
Note that the number of Offers is controlled by the Configuration Settings in your publisher dashboard. Log into your dashboard, click on Settings>Configuration from the side menu and then select the number of Offers you would like to have returned.
The adpx_fp attribute in the body of the Fetch Offers and Fetch Perkswall Offers calls is a special parameter that aids in overall Offer performance. It should be populated with a unique end-user identifier as an alpha-numeric string. AdsPostX uses the adpx_fp value to frequency cap Offers on a unique user basis as well as exclude Offers from showing again when a user opts-out for a certain offer.
Perkswall Offers returns all Perkswall enabled Offers available to the publisher. These Offers can be used by the publisher to construct their Perkswall in a branded experience. In order to use this endpoint, contact your account manager to enable Perkswall features.
Upon a successful response from the Fetch Offers API request, the body of the reponse will include a data object that contains an array of objects that can be used to construct your Offers. The following attributes are the relevant attributes to construct your Offers with.
offers array of objects
Contains the copy, creatives, and resources to construct each Offer.
count integer
Number of Offers returned from the call.
privacy_url URL
URL to AdsPostX's current end user privacy policy page.
Upon a successful response from the Fetch Offer's API request, generate Offers using the Offer fragments provided for each returned Offer.
Remember to implement impression tracking using the pixel attribute for each displayed Offer. A successful GET call to the Pixel URL is required to successfully record delivery on the AdsPostX Dashboard.
This allows AdsPostX to:
- Accurately calculate and present performance statistics such as click-through rate (CTR), eCPM and other metrics.
- Use performance data to optimize ad delivery on future traffic.
- Generate and display first Offer using the fragments of the Offer returned in the response
- Implement the Impression Beacon URL for the first Offer
- If user engages with the negative call-to-action, render the second Offer (and implement the Impression Beacon URL for this Offer)
- Continue through the sequence based on user engagement
When retrieving Offer, we provide a creatives attribute with each returned Offer, which lists creatives available for use in your Offers.
Included with each creative is an is_primary boolean attribute. You can use any of the creatives available depending on the platform you are rendering or default to the primary creative if you are unsure.
The Native Ads API also supports on-the-fly image transformations: by simply adding the query parameter "width=XXX" into the image url (replace XXX with a suitable integer value for width, depending on the device resolution). The query parameters "height=XXX" or "?aspect_ratio=X:Y" are also available as on-the-fly image processing directives on images.
We also provide an aspect_ratio attribute for each creative which can be helpful in selecting an image for the Offer.
An aspect_ratio with:
- a value of 1 = square image
- a value < 1 signifies generally portrait
- a value > 1 signifies generally landscape
In addition to tracking impressions, the Offers response also provides a beacons object, containing the tracking URLs for events no_thanks_click (to be fired when user clicks the Negative CTA element) and close (to be fired when user closes the Offer container or when the user has browsed through all the available Offers).