Perkswall Anatomy
MomentScience's Perkswall provides a seamless way to integrate curated offers and perks into your platform. Using the Perkswall API, you can fetch offer data and design a Perkswall that perfectly aligns with your branding and user experience goals.
This flexible solution empowers you to customize the look, feel, and behavior of the Perkswall, ensuring it blends naturally into your platform while delivering a personalized, engaging experience for your users.
This document provides an in-depth look at the Perkswall structure and how to maximize its functionality after retrieving data from the API.
Perkswall Sections
A. Perkswall Header The header section is customizable based on your preferences and typically showcases your brand identity. This can include an image, a specific color scheme, or custom code tailored to your design requirements.
B. Featured Offers This section highlights up to three featured offers. Users can scroll through these offers, providing an engaging way to display important promotions or deals.
C. Perkswall Body The body section contains a continuous list of offers. As users scroll, more offers will be loaded, displaying additional offers as they progress down the page.
The API response includes three key components:
- Offers: A list of available offers, each containing metadata like id, title, description, image, CTAs, and tracking pixels.
- ο»ΏSettings: Configuration options for Perkswall behavior, layout, and branding.
- ο»ΏStyles: Customization options for the visual appearance, such as text styles, colors, and button designs.
By understanding and leveraging these sections, you can create a Perkswall experience tailored to your platform's requirements.
The Perkswall header can be tailored to match your platformβs branding and design by configuring settings in the dashboard, which are reflected in the API responses.
This approach provides flexibility: you can either use the API to dynamically render the header based on dashboard configurations or create a fully customized header independently, ignoring the API-provided values if desired.
The header style is defined bystyles.header.style and supports the following options:
- light: A default clean white background for a minimalist appearance.
- image: A header with a background image. The image URL can be found in styles.header.image.
- color: A header with a static background color. The color value is returned in styles.header.color.
- custom: A fully customized header using JavaScript. The custom code is returned in the settings.custom_head parameter.
The featured offers functionality allows you to highlight specific offers within your Perkswall.
To check if featured offers are enabled for your account, refer to the data.settings.featured_offers parameter:
- true: Featured offers are enabled for your Perkswall.
- false: Featured offers are disabled for your Perkswall.
When enabled, the data.settings.featured_offer_list provides the IDs of up to three featured offers. You can use the IDs from data.settings.featured_offer_list to identify the corresponding offers in the data.offers[] array by matching them with the data.offers[].id field.
A. Offer Icon Image: Displays the creative offer icon from data.offers[].creatives[] where creative_typeis icon_image.
B. Advertiser Name: Displays the offerβs advertiser name, retrieved from data.offers[].advertiser_name.
C. Offer Short Headline: Displays the offerβs short headline, retrieved from data.offers[].short_headline.
D. Offer Short Description: Provides a brief offer description from data.offers[].short_description.
E. Positive CTA Button: Displays the call-to-action text, retrieved from data.offers[].cta_yes.
F. Perkswallet Button: Allows users to save the offer for later use and is displayed only if data.offers[].perkswallet_enabled is set to true.
ο»ΏG. Offer Hero Image: Displays the offer's hero image, retrieved from data.offers[].creatives[] where creative_type is hero_image.ο»Ώ
H. Offer Title: Displays the full offer title, retrieved fromdata.offers[].title.
I. Offer Description: Provides the detailed offer description, retrieved from data.offers[].description.
1. Positive CTA Button
- Text Source: Retrieve the button text from data.offers[].cta_yes.
- Action: When the user clicks the positive CTA button, direct them to the URL specified in data.offers[].click_url.
ο»Ώ2. Negative CTA Buttonο»Ώ
- Note: The negative CTA button data.offers[].cta_no is optional. Implementation is not required unless specified. If you're considering its usage, contact your account manager for guidance on its purpose.
ο»Ώ3. Close Buttonο»Ώ
- Note: The close beacon data.offers[].beacons.close does not indicate the closure of the Perkswall and is typically not required for implementation. If you're unsure whether to use this, reach out to your account manager for clarification.
Each offer includes a set of creative images, each serving a specific purpose. Below are the supported creative types and their recommended specifications:
- Icon Creative
- Type: icon_image
- Description: Represents the offer's icon or brand logo.
- Expected Size: 250 Γ 250 px (Β±10% size variation).
- ο»ΏHero Creative
- Type: hero_image
- Description: Represents the offer in the Perkswall Featured Section. It can also be used if a larger "offer page" is implemented, providing a more detailed display of the offer.
- Expected Size: 1000 Γ 280 px (Β±10% size variation).
- Offer Creative
- Type: offer_image
- Description: An additional image relevant to the offer.
- Expected Size: Based on design requirements.
- Constraint: Ensure the uploaded and received image matches the expected dimensions for optimal display.
Creatives uploaded via the dashboard appear first in data.offers[].creatives and include a user_idattribute matching your ID to identify them as your uploads.
The Offer Impression Pixel tracks when an offer is displayed to the user, capturing essential data for performance monitoring and analytics. It triggers when the associated creative is rendered on the userβs screen.
- Parameter Location: data.offers[].pixel
- Type: URL
Usage Guidelines
- Fire the pixel as soon as the creative becomes visible to the user.
- Ensure the pixel fires only once per impression to avoid duplicate tracking.
- Send an HTTP GET request to the URL in data.offers[].pixel.
The API response includes a styles object, which defines the visual appearance and behavior of various UI components in your Perkswall. These style settings are managed through the Perkswall integration page in the dashboard.
Any changes made to the styles settings in the dashboard are automatically reflected in your API response, ensuring consistency across your integration.
For more details on editing these settings, refer to the following demo.
The API response includes a settings object that defines your Perkswall's configuration. This object contains nested properties such as tile_count, fav_icon_logo, and other related settings.
You can specify and customize these settings directly from the dashboard. Changes made in the dashboard are automatically reflected in the API response, allowing for easy modification and management of your Perkswall's behavior and appearance.
To learn more about editing your settings, refer to the following demo.
ο»Ώ
π’ If you're running into any issues while going through the integration process, feel free to contact us at [email protected]ο»Ώ