Perkswall Implementation Checklist
Use this checklist to confirm your Perkswall API integration meets all functional, tracking, and performance requirements. Follow the steps in order to ensure a smooth deployment.
Parse and extract offer data
Retrieve the offers array from the API response.
- Importance: Each object contains the attributes required to construct and display an offer.
Extract essential attributes for display:
- title: Main offer headline. Use short_headline for smaller placements to avoid truncation.
- advertiser_name: Advertiser name.
- description: Detailed copy (≤ 220 characters). Use short_description in compact layouts.
- click_url: Destination URL. Use exactly as returned and do not modify query parameters.
- image: Primary offer image.
- pixel: Impression beacon URL for tracking.
Construct and display offers
Render terms_and_conditions as HTML when present.
- Importance: Preserves formatting for legal or promotional terms. If missing, no special terms apply.
Display offers in sequence.
- Render the first offer in your placement area.
- Trigger its pixel immediately after the offer is visible to the user.
- Move to subsequent offers in order, ensuring each impression is recorded.
- Avoid preloading multiple offers in the viewport unless you will fire all corresponding pixels immediately.
Implement impression tracking
Fire a GET request to offers[].pixel whenever an offer becomes visible.
- Importance: Records impressions in MomentScience reporting for CTR, eCPM, and CR.
If offers[].adv_pixel_url is present, fire a GET request to it at the same time.
- Importance: Satisfies advertiser tracking and third‑party verification.
Do not cache or debounce impression beacons beyond viewability logic.
- Importance: Prevents undercounting and data latency.
Use and optimize creatives
Select the primary creative from creatives[] where is_primary: true. If missing, use the image attribute on the offer.
- Importance: Ensures consistent visual presentation.
Supported creative types:
- offer_image: Standard image; size based on your layout.
- hero_image: Featured banner (1000×280 px ±10%).
- icon_image: Square logo or icon (250×250 px ±10%).
When using a proxy server
Pass the end user’s IP address as the ip parameter in the request payload.
- Importance: Used for geo‑targeting and validating eligible offers.
Pass the User‑Agent string as the ua parameter in the request payload.
- Importance: Used for device and platform targeting.
When implementing LoyaltyBoost (Rewarded offers)
Only implement LoyaltyBoost if you can identify your users to reward them with your loyalty currency.
Request LoyaltyBoost offers by passing the loyaltyboost query parameter with values 1 or 2.
- 1: Include LoyaltyBoost offers.
- 2: Return only LoyaltyBoost offers.
- Importance: Ensures the response matches your rewarded experience requirements.
Set up a postback URL with MomentScience. See Handling Postback Events.
- Importance: Receives server‑to‑server notifications when users convert, including payout amount (USD), so you can credit loyalty rewards accurately.
Include a stable user fingerprint in the payload as adpx_fp.
- Importance: Prevents showing a LoyaltyBoost offer to a user who has already converted on it.
Include a custom key‑value in the payload that identifies where to credit the reward (for example, loyaltyid=12345566).
- Importance: This value is returned in postbacks with the payout amount, allowing you to map the conversion to the correct account and calculate reward amounts.
Need assistance? Contact our support team at [email protected]