Partner API

Pagination

Improve your customer experience when browsing multiple pages. When generating product ads, you will receive a memoryToken that can be sent in subsequent requests to exclude previously served ads.

🚧

Product Ads Only!

This capability is only currently supported for CitrusAd's product ads.

How to implement pagination on your site?

When generating product ads, in the response you will receive a memoryToken.

{
    "ads": [
        {
            "id": "display_3rGiryPskhQusmsf43nghbQwnqo3NzMzNjU3",
            "gtin": "7733657",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400917769Z",
            "position": 1
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

When a customer is navigating to the next page, you should send this token in your next ad request.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0=",
    "options": {
                         "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3    
}

Using this token, CitrusAd will exclude any previously served ads to the customer if the sessionId are identical to the token's request.

🚧

Standard Integration!

This capability is only currently supported for CitrusAd's product ads.

How does it work?

When CitrusAd receives a memoryToken in the ad request, any previously served ads for the sessionId will be excluded from the ad response. This ensures a wider variety of ads served back to your customer on a multi-page journey.

When this token does not exist on the request, ad generation will be done as per current process with no exclusions applied. A token will always be provided after ad generation for a retailer to opt into utilising.

The memory token contains encoded information that allows CitrusAd to determine the ads that have been served previously (either in a single request, or over a period of multiple chained requests).

In the event of an irrelevant token being sent to CitrusAd (such as a different context), ads are returned as if no token was provided in the ad request.

⚠

️ Do you request more ads than served to your website?

If you're a retailer that requests more ads from CitrusAd than is served to your customer, you may not receive many ads on subsequent pages. If you request 15 ads and only serve 4 to your customer, when receiving the memoryToken, CitrusAd will exclude all 15-20 ads previously served to you in the subsequent ad response.

Example request flow

Frequently asked questions

Can I use this token across multiple customer searches to exclude products on the larger customer journey?

No, if CitrusAd receive an ad request that does not match the token's ad request, it is ignored and ads are generated as if there was no token provided.

What if I send a memoryToken and it is malformed?

CitrusAd will ignore the token and process the request as if it is a normal request.

How many pages can I paginate for?

By default, this is 5, this is the best balance of performance and saturation that CitrusAd has seen across multiple clients.

As of CitrusAd's release 39.0, this can be configured via your Technical Account Manager.

What happens when you are out of ads to serve such as page 5-10 on the default configuration?

The memoryToken is configured on CitrusAd's side to store ads from the number of pages in the configuration. For example, if the configuration is the default of 5 pages, CitrusAd will begin re-serving ads from page 7.

Pagination request 6 (page 6): the memoryToken contains information on the previous 5 pages' ads, therefore no ads from the previous 5 pages will be served.

Pagination request 7 (page 7): the ads from page 1 are eligible to be served.

What happens if I am out of ads before page 5 on the default configuration?

If for example, by page 3 you are out of ads, we will begin serving ads by page 7, as we store the total number of pages in the configuration as the previously served ads that shouldn't be served again.