Integrating with PerksWallet

22 min

Who is this for: Developers who want to embed PerksWallet directly within their own app or website with full control over the user experience.

Outcome: Integrate Embedded PerksWallet via API or JavaScript SDK, enabling users to save and access offers within the publisher's own interface using a pub_user_id.

Overview

This guide covers the Embedded PerksWallet integration, for partners who want full control over the wallet experience within their own app or website.

This document provides a detailed walkthrough for integrating PerksWallet into your product using our APIs or JavaScript SDKs.

Looking for a simpler option? If you prefer a zero-code solution, see Integrating with Hosted PerksWallet instead. With Hosted PerksWallet, MomentScience manages everything, no integration required.

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.

Embedded 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

Perkswall API

Integration via JavaScript SDK

Moments

Add the following script before the closing </head> tag

<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:

<div id="adpx_container"></div>

Add the following script before the closing </body> tag

<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 partner'sID 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.

{
  "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

<div id="adpx_container"></div>

Add the following script before the closing </body>tag

<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]