PerksWallet

Integrating with PerksWallet

23min

Overview
This guide provides a detailed walkthrough for integrating PerksWallet into your product. Whether you're using our APIs or JavaScript SDKs, this document outlines the necessary steps for a smooth integration.
Prerequisites
Before you begin, ensure the following:
PerksWallet must be enabled for your account. Contact your MomentScience account manager to activate it.
You need an API Key with access to "PerksWallet." Refer to API Key Documentation to learn how to obtain one.
Understanding pub_user_id
The pub_user_id is a unique, non-PII identifier for each user. It plays a critical role in linking offers to individual users.
Ensure the pub_user_idremains consistent across sessions and devices.
Do not use personally identifiable information (PII) such as email addresses or phone numbers.
You can generate this identifier using any logic, as long as it’s unique for each user.
The pub_user_idis a required field in all requests and is essential for saving and retrieving offers.
﻿
Integrating  Methods
﻿You can integrate PerksWallet into your product using one of the following methods: ﻿
Perkswall API
Moments API
Moments JS SDK
Perkswall SDK
The core requirement for all integrations is providing a pub_user_id, a stable user identifier that allows offers to be saved and retrieved across sessions and devices.
Integration via API
When integrating with Perkswall API or Moments API, the process is the same. The key step is ensuring the pub_user_idis included in the request body for both saving and retrieving offers.
Try It Out 
Moments API
<iframe src="https://hopp.sh/e/G3RrLqRXm6Qz" title="Hoppscotch Embed" style="width: 100%; height: 480px; border-radius: 4px; border: 1px solid rgba(0, 0, 0, 0.1);"></iframe>
<iframe src="https://hopp.sh/e/G3RrLqRXm6Qz" title="Hoppscotch Embed" style="width: 100%; height: 480px; border-radius: 4px; border: 1px solid rgba(0, 0, 0, 0.1);"></iframe>
﻿
Perkswall API
<iframe src="https://hopp.sh/e/VnNgPL864j75" title="Hoppscotch Embed" style="width: 100%; height: 480px; border-radius: 4px; border: 1px solid rgba(0, 0, 0, 0.1);"></iframe>
<iframe src="https://hopp.sh/e/VnNgPL864j75" title="Hoppscotch Embed" style="width: 100%; height: 480px; border-radius: 4px; border: 1px solid rgba(0, 0, 0, 0.1);"></iframe>
﻿
Integration via JavaScript SDK
Moments 
Add the following script before the closing </head> tag
JS
<script type="module">
    (function (window) {
        // Configure Moments with your account settings
        window.AdpxConfig = {
            accountId: 'fbe6000000f803ef4', // Replace with your unique account ID
            autoShow: true // Automatically show the Moments widget when loaded
        };

        // Define the user object using a stable pub_user_id
        window.AdpxUser = {
            pub_user_id: 'user-123' // Replace with your unique user ID
        };

    })(window.self !== window.top ? window.top : window);

    (async function (window) {
        const target = window.document.head || window.document.body;
        const script = window.document.createElement('script');
        script.type = 'text/javascript';
        script.src = 'https://cdn.pubtailer.com/launcher.min.js';
        script.importance = 'high';
        script.crossOrigin = 'anonymous';
        script.async = true;
        script.id = 'adpx-launcher';
        target.appendChild(script);
        await new Promise(function (resolve) {
            window.Adpx
                ? resolve()
                : window.document
                    .getElementById('adpx-launcher')
                    .addEventListener('load', function () { resolve(); });
        });
        window.Adpx.init(AdpxConfig);
    })(window.self !== window.top ? window.top : window);
</script>
<script type="module">
    (function (window) {
        // Configure Moments with your account settings
        window.AdpxConfig = {
            accountId: 'fbe6000000f803ef4', // Replace with your unique account ID
            autoShow: true // Automatically show the Moments widget when loaded
        };

        // Define the user object using a stable pub_user_id
        window.AdpxUser = {
            pub_user_id: 'user-123' // Replace with your unique user ID
        };

    })(window.self !== window.top ? window.top : window);

    (async function (window) {
        const target = window.document.head || window.document.body;
        const script = window.document.createElement('script');
        script.type = 'text/javascript';
        script.src = 'https://cdn.pubtailer.com/launcher.min.js';
        script.importance = 'high';
        script.crossOrigin = 'anonymous';
        script.async = true;
        script.id = 'adpx-launcher';
        target.appendChild(script);
        await new Promise(function (resolve) {
            window.Adpx
                ? resolve()
                : window.document
                    .getElementById('adpx-launcher')
                    .addEventListener('load', function () { resolve(); });
        });
        window.Adpx.init(AdpxConfig);
    })(window.self !== window.top ? window.top : window);
</script>
﻿
Perkswall
Add the container where the widget will be rendered:
JS
<div id="adpx_container"></div>
<div id="adpx_container"></div>
﻿
Add the following script before the closing </body> tag
JS
<script>
  window.AdpxConfig = {
    accountId: "fbe6000000f803ef4", // Replace with your account ID
    themeId: "Standard-Theme",     // Replace with your theme ID
    containerId: "adpx_container"
  };

  window.AdpxUser = {
    // Include user info here
    pub_user_id: "user-123",     // Replace with your unique user ID
  };

  const adpx = document.createElement('script');
  adpx.type = 'text/javascript';
  adpx.async = true;
  adpx.src = 'https://cdn.adspostx.com/launcher.perkswall.js';
  document.getElementsByTagName('head')[0].appendChild(adpx);
</script>

<script>
  window.AdpxConfig = {
    accountId: "fbe6000000f803ef4", // Replace with your account ID
    themeId: "Standard-Theme",     // Replace with your theme ID
    containerId: "adpx_container"
  };

  window.AdpxUser = {
    // Include user info here
    pub_user_id: "user-123",     // Replace with your unique user ID
  };

  const adpx = document.createElement('script');
  adpx.type = 'text/javascript';
  adpx.async = true;
  adpx.src = 'https://cdn.adspostx.com/launcher.perkswall.js';
  document.getElementsByTagName('head')[0].appendChild(adpx);
</script>
﻿
﻿
Saving an Offer
When a user wants to save an offer for later, they can click the "Save for Later" CTA within the PerksWallet experience.
Saving via API
﻿To save offers via the Moments API or Perkswall API, follow these steps:﻿
Include the pub_user_idin the API request body.
Extract save_for_later_urlfrom the API response (offers[].save_for_later_url).
On CTA click, make a POST request to save_for_later_url.
Once the POST request is made, the offer is saved to the user’s wallet and can be retrieved later using the same pub_user_id.
If pub_user_idis missing in the request body, save_for_later_url will be null.
Saving via JavaScript SDK
If you are using the SDK, the saving process is automatically handled.
The SDK automatically saves the offer when a user clicks the "Save for Later" button within a PerksWallet experience.
The saved offer is linked to the pub_user_idyou provided during integration.
﻿
Retrieving User's Wallet
To fetch offers saved by a user, use the following API endpoint. This applies whether you're integrating via the Moments API or Perkswall API.
 Using the API﻿
HTTP Method: GET
Endpoint: https://api.perkswallet.com/api/publisher/user/{{pub_user_id}}/saved/campaigns.json﻿
Path Parameters:
Parameter
Type
Description
pub_user_id
String
The unique identifier of the user whose wallet you want to retrieve. 
Header Parameter
Parameter
Type 
Description
pwaas-api-key
String
API key with access permission to PerksWallet. Required to authenticate and authorize the request.
Response Parameters
Parameter
Type
Description
data
array
List of saved offers for the user. If no offers are saved, this will be an empty array.
data[].id
integer
Unique ID of the saved offer.
data[].user_id
string
Unique identifier for the user who saved the offer.
data[].campaign_id
string
ID of the campaign associated with the offer.
data[].publisher_id
string
The publisher's ID from which the user saved the offer
data[].session_id
string
Unique session identifier when the offer was saved.
data[].converted_at
string/null
Timestamp of when the offer was claimed (if applicable). Returns nullif not yet claimed.
data[].created_at
string
Timestamp of when the offer was saved, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
data[].updated_at
string
Timestamp of the last update to the saved offer record.
data[].campaign
object
Details of the campaign associated with the saved offer.
data[].campaign.id
integer
Unique campaign ID.
data[].campaign.advertiser_name
string
Name of the advertiser providing the offer.
data[].campaign.description
string
Full description of the offer.
data[].campaign.short_description
string
Shorter version of the offer description.
data[].campaign.headline
string
Primary offer headline.
data[].campaign.short_headline
string
A more concise version of the headline.
data[].campaign.positive_cta
string
Call-to-action text for the offer (e.g., "Start My Free Trial").
data[].campaign.primary_creative
string
URL to the primary creative (image) of the offer.
data[].campaign.is_active
boolean
Indicates whether the offer is still active (true or false).
data[].click_url
string
URL to claim the offer.
Example Response
{
  "data": [
    {
      "id": 1000,
      "user_id": "200",
      "campaign_id": "100",
      "publisher_id": "2222",
      "session_id": "a21cec...",
      "converted_at": null,
      "created_at": "2025-04-03T10:47:27.404+00:00",
      "updated_at": "2025-04-03T10:47:27.404+00:00",
      "campaign": {
        "id": 100,
        "advertiser_name": "Ancestry",
        "description": "...",
        "short_description": "...",
        "headline": "Discover Your Roots - Free Ancestry Trial!",
        "short_headline": "Discover Your Roots - Free Trial!",
        "positive_cta": "Start My Free Trial",
        "mini_text": "<p><br></p>",
        "primary_creative": "https://...",
        "is_active": true,
        "last_sync_at": "2025-02-07T05:03:17.049Z",
        "created_at": "2025-02-07T05:03:17.049+00:00",
        "updated_at": "2025-02-07T05:03:17.049+00:00"
      },
      "click_url": "https://trk.pubtailer.com/sdk/offer-click?o_id=4460&c_id=1753&sess_id=a21cec89008306ec70d4315f6d55a045ae8761fc&p_id=3065"
    }
  ]
}
{
  "data": [
    {
      "id": 1000,
      "user_id": "200",
      "campaign_id": "100",
      "publisher_id": "2222",
      "session_id": "a21cec...",
      "converted_at": null,
      "created_at": "2025-04-03T10:47:27.404+00:00",
      "updated_at": "2025-04-03T10:47:27.404+00:00",
      "campaign": {
        "id": 100,
        "advertiser_name": "Ancestry",
        "description": "...",
        "short_description": "...",
        "headline": "Discover Your Roots - Free Ancestry Trial!",
        "short_headline": "Discover Your Roots - Free Trial!",
        "positive_cta": "Start My Free Trial",
        "mini_text": "<p><br></p>",
        "primary_creative": "https://...",
        "is_active": true,
        "last_sync_at": "2025-02-07T05:03:17.049Z",
        "created_at": "2025-02-07T05:03:17.049+00:00",
        "updated_at": "2025-02-07T05:03:17.049+00:00"
      },
      "click_url": "https://trk.pubtailer.com/sdk/offer-click?o_id=4460&c_id=1753&sess_id=a21cec89008306ec70d4315f6d55a045ae8761fc&p_id=3065"
    }
  ]
}
﻿
Showing User's Wallet with SDK
Add this container element where you want the Saved Offers widget to appear 
Add this container element where you want the Saved Offers widget to appear
JS
<div id="adpx_container"></div>
<div id="adpx_container"></div>
﻿
Add the following script before the closing </body>tag 
JS
<script>
  window.PwaasConfig = {
    accountId: "fbe6000000f803ef4", // Replace with your account ID
    pub_user_id: "user-123", // Replace with your user's unique ID
    themeId: "Standard-Theme", // Optional: use your own theme if available
    containerId: "adpx_container"
  };

  const adpx = document.createElement('script');
  adpx.type = 'text/javascript';
  adpx.async = true;
  adpx.src = 'https://cdn.adspostx.com/launcher.pwaas.js';
  document.getElementsByTagName('head')[0].appendChild(adpx);
</script>

<script>
  window.PwaasConfig = {
    accountId: "fbe6000000f803ef4", // Replace with your account ID
    pub_user_id: "user-123", // Replace with your user's unique ID
    themeId: "Standard-Theme", // Optional: use your own theme if available
    containerId: "adpx_container"
  };

  const adpx = document.createElement('script');
  adpx.type = 'text/javascript';
  adpx.async = true;
  adpx.src = 'https://cdn.adspostx.com/launcher.pwaas.js';
  document.getElementsByTagName('head')[0].appendChild(adpx);
</script>
﻿
﻿
Deleting Saved Offers
Using the API
To delete a saved offer, use the following API request:
HTTP Method: DELETE
Endpoint:  https://api.perkswallet.com/api/publisher/user/{{pub_user_id}}/saved/campaign/{{campaign_id}}.json﻿
Path Parameters:
Parameter
Type
Description
pub_user_id
String
The unique identifier of the user requesting deletion.
campaign_id
String
The ID of the offer the user wants to remove.
Header Parameter
Parameter
Type 
Description
pwaas-api-key
String
API key with access permission to PerksWallet. Required to authenticate and authorize the request.
If the request is successful, the API will return a confirmation message indicating the offer has been deleted.
Using SDK
If you are implementing using the SDK, deletion is handled automatically.
The user will see a delete icon next to each saved offer.
Upon clicking the icon, a confirmation message will appear.
If the user confirms, the offer will be deleted from their saved list.
﻿
📢 If you're running into any issues while going through the integration process, feel free to contact us at [email protected]﻿

Parameter	Type	Description
pub_user_id	String	The unique identifier of the user whose wallet you want to retrieve.

Parameter	Type	Description
pwaas-api-key	String	API key with access permission to PerksWallet. Required to authenticate and authorize the request.

Parameter	Type	Description
data	array	List of saved offers for the user. If no offers are saved, this will be an empty array.
data[].id	integer	Unique ID of the saved offer.
data[].user_id	string	Unique identifier for the user who saved the offer.
data[].campaign_id	string	ID of the campaign associated with the offer.
data[].publisher_id	string	The publisher's ID from which the user saved the offer
data[].session_id	string	Unique session identifier when the offer was saved.
data[].converted_at	string/null	Timestamp of when the offer was claimed (if applicable). Returns nullif not yet claimed.
data[].created_at	string	Timestamp of when the offer was saved, in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
data[].updated_at	string	Timestamp of the last update to the saved offer record.
data[].campaign	object	Details of the campaign associated with the saved offer.
data[].campaign.id	integer	Unique campaign ID.
data[].campaign.advertiser_name	string	Name of the advertiser providing the offer.
data[].campaign.description	string	Full description of the offer.
data[].campaign.short_description	string	Shorter version of the offer description.
data[].campaign.headline	string	Primary offer headline.
data[].campaign.short_headline	string	A more concise version of the headline.
data[].campaign.positive_cta	string	Call-to-action text for the offer (e.g., "Start My Free Trial").
data[].campaign.primary_creative	string	URL to the primary creative (image) of the offer.
data[].campaign.is_active	boolean	Indicates whether the offer is still active (true or false).
data[].click_url	string	URL to claim the offer.

Parameter	Type	Description
pub_user_id	String	The unique identifier of the user requesting deletion.
campaign_id	String	The ID of the offer the user wants to remove.

Parameter	Type	Description
pwaas-api-key	String	API key with access permission to PerksWallet. Required to authenticate and authorize the request.

PerksWallet

Customizing your PerksWallet Integration

Integrating with PerksWallet

Overview

Prerequisites

Understanding pub_user_id

Integrating Methods

Integration via API

Try It Out

Integration via JavaScript SDK

Moments

Perkswall

Saving an Offer

Saving via API

Saving via JavaScript SDK

Retrieving User's Wallet

Using the API﻿

Showing User's Wallet with SDK

Deleting Saved Offers

Using the API

Using SDK

Using the API