Perkswall API
The MomentScience Perskwall API is a powerful platform that allows publishers to easily integrate a perks "gallery" within their app or website using any language that supports the ability to make RESTful calls.
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 the Perkswall API, contact your account manager to enable Perkswall on your account.
The typical flow to generate and serve Offers via a Perkswall is as follows:
- Make a Fetch Perkswall Offers API call to MomentScience 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.
Method: POST Base URL: https://api.adspostx.com/native/v2/perkswall.json
Parameter | Description | Type | Example |
|---|---|---|---|
Content-Type required | Should be application/json | string | application/json |
Parameter | Description | Type | Example |
|---|---|---|---|
api_key required | Your API Key. Obtain your API Key. Required Permission: Ads/Offers | string | 4bbdefc2-b130-424d-8170-54bdcb98e64e |
loyaltyboost optional | Include LoyaltyBoost offers in response; Values: 0 = None 1 = True 2 = Only | string | 0|1|2 |
creative optional | Returns offers with at least one creative (image) if set to true. | string | 0|1 |
Parameter | Description | Type | Example |
|---|---|---|---|
ua recommended | The User-Agent of the end-user required for proper targeting. If proxying requests via a server call, be sure to pass through the User-Agent of the end-user. | string | Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.6099.43 Mobile Safari/537.36 |
ip recommended | IP address of the end user to be passed through. Used for targeting. | string | |
adpx_fp recommended | A unique identifier for the end user; Not required but highly recommended. More information can be found below. | string | |
dev optional | Returns a test response. Ignores geo restrictions. No activity is recorded. | string | 0|1 |
subid optional | An id to identify various usages of the Fetch Perkswall Offers API. | string | mobile_android_app_post_transaction |
<string> optional | Custom Key-Value payload attributes. You can add any number of custom key-value payload attributes to the payload that you want to use to add additional details. All payload attributes are passed back on conversion reports and can be reported on in relation to impression and clicks. | string | membershipID: "A45GRE987343PKD" |
The adpx_fp attribute in the body of the 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. MomentScience 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.
When 'dev' is set to '1', the sandbox environment is enabled for testing purposes only, with no activity recorded in production. In this mode, geo-targeting is ignored for publishers, ensuring that all offers are returned in Offer responses for comprehensive testing.
Upon a successful response from the Fetch Perkswall 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.
Upon making an API call, the following attributes are returned in the response to construct your Perkswall Offers with.
offers array of offer objects
Contains the copy, creatives, and resources to construct each Offer. Each offer object has the following attributes:
count integer
Number of Offers returned from the call.
privacy_url URL recommended to implement
URL to MomentScience's current end user privacy policy page.
Upon a successful response from the Fetch Perkswall 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 MomentScience Dashboard.
This allows MomentScience to:
- Accurately calculate and present performance statistics such as click-through rate (CTR), eCPM and other metrics.
- Use performance data to optimize Offer delivery for future traffic.
- Generate and display first Offer using the fragments of the Offer returned in the response.
- Implement the Impression Beacon URL (pixel) for the first Offer
- Render the second Offer (and implement the Impression Beacon URL for this Offer)
- Continue through all the other Offers to construct your Perkswall experience.
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 Moments 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
We recommend you go through our Perkswall API integration checklist to ensure that you have not missed any integration steps. This will help you gain the full advantage of the features provided by MomentScience.
📢 If you're running into any issues while going through the integration process, feel free to contact us at [email protected]