1 of 33

Project Agora V2

Overview

What is Project Agora Commerce

Project Agora Commerce is a scalable, auction based advertising platform built for e-commerce retailers to easily integrate into. The API keeps the e-commerce retailer in full control on how, when, where and how often ads are shown. If you haven't heard of Project Agora Commerce before, or you are unfamiliar with the product's features view the https://projectagora.com/ site.

What Project Agora Commerce Offers

In summary, the Project Agora Commerce Ad Platform is a unique digital ad serving engine that provides relevant native Product Listing Ads and Banner Ad content in real time.

Using first party sales data from the retailer, Project Agora Commerce is able to deliver relevant and personalised ad content to the retailer's e-commerce server in the form of barcode and image URL, each and every time a new page is loaded, and does so in less than 50ms 95 percent of the time.

Project Agora Commerce makes it possible for your retail e-commerce website to offer Product Listing Ads and Banner Ads to advertisers, thereby increasing retailer revenue. This is done with the "Project Agora API".

The Project Agora Commerce API makes it possible for you (the retailer) to place advertisements on your e-commerce website and email marketing based on parameters that you set. After you define the slots on your websites in which advertisements are placed, the slots become available for advertisers to bid on. You (the retailer) determine which items in your catalog you want to advertise, and Project Agora Commerce makes it possible for advertisers to bid on the opportunity to advertise those items.

Basic Overview

In its very simplified form, Project Agora Commerce allows advertisers to create Ad campaigns that appear on each retailer's site. Advertisers will be able to promote their products to the top of a retailer's website and track the performance of those products in real time. Advertisers use the Project Agora Commerce Admin Portal to select products, budgets, advertising strategies and “keywords” that they wish for their products to appear at the top of the page for.

How Project Agora Commerce Works

The Project Agora Commerce API is organised around REST. The Project Agora Commerce API has predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. This API uses built-in HTTP features such as HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

Authentication to the Project Agora Commerce API is handled through the use of API keys. These are used during communication between your backend and the Project Agora Commerce API.

The Project Agora Commerce API supports uploading products, catalogs, customers, and order information. This data is used in the generation of ads. You can use the Project Agora Commerce API to request ads and to report on user interactions with those ads.

API Introduction

View the API Introduction to gain an overview of what is required to integrate with Project Agora Commerce.

Ad Types

Project Agora Commerce are capable of serving various types of ads:

Sponsored Product Listing Ads
Discovery Sponsored Product Listing Ads
Static Banner Ads

Learn more about each ad type on the What Ads Can Project Agora Commerce Serve page:

Integration Workflow Options

We support many integration options depending on your individual infrastructure and needs. See the "Integration Workflow Options" page to learn more:

What Ads Can Project Agora Commerce Serve?

What types of Ads Project Agora Commerce serves.

The Project Agora Commerce platform enables retailers to utilize one ad platform for multiple ad types, removing the need for multiple connections to different ad servers.

Discovery Sponsored Product Listing Ads (DSPLs)

Discovery Sponsored Product Listing ads which drives in even higher discoverability rates and are also merged with the retailer's organic listings before being served to the end user of the retailer's site.

Static Banners

Banner advertising is a brilliant introducer to an advertiser's brand message and absolutely influences online and in store sales.

The Project Agora Commerce Ad platform enables retailers to utilize one ad platform for both Product Ads as well as Banner Ads (including any form of graphical ad such as image, video or animation) removing the need for multiple connections to different ad servers.

Post Checkout Banner Ads (Optional)

Post Checkout Banners are an effective way to generate brand new revenue from a variety of new suppliers by allowing approved third party advertisers to bid for ad placement.

Advertisers are able to target customers based on relevancy, as well as items a customer has purchased within their completed order. Approved third party advertisers may also utilize this opportunity to bid for ad placements that can refer away from the retailer's site.

Banner X (Responsive Banner) Ads (Optional)

Banner X ads are responsive banner ads. These are multi-component banners that are served to a retailer's front end. CitrusAd sends each individual component of the banner and the styling of these banners is handled by the retailer's front end. Banner X ads remain on brand and can render on any screen size.

Accessibility

These dynamic banner ads contain additional accessibility information that helps support blind and disabled shoppers. Your banner ads will contain all required information for screen reader users.

Readability

Unlike regular banner ads, ads utilise native text instead of embedded text. This boosts the clarity and readability of your ads, and reduces the risks of compression and stretching on embedded text content.

Responsivity

Many banner ads are a single image embedded onto a site regardless of browser widths or digital touchpoint. In high and atypical browser widths these banners are vulnerable to stretching and quality loss. Banners respond to any browser width and maintain image quality as images resize and reposition in response to the browser’s width.

Integration

API Introduction

An overview of the Project Agora Commerce API for integrators.

Before you can integrate with Project Agora Commerce, you will need a Retailer team created for you. Contact Project Agora Commerce to create integration teams.

Project Agora Commerce Endpoints

Project Agora Commerce uses various endpoints to sync data and generate ads. A brief summary is below:

Endpoint

Use

Description

catalogs *

Syncing catalogs

Used to create catalogs Via API

catalog-products *

Syncing products

Used to create and update product data within a catalog

customers *

Syncing customers

Used to create and update customer data within a catalog

orders

Sending orders

Used to send order data to Project Agora Commerce

generate

Generating ads

Used to generate product ads and banner ads

bannerx

Generating ads

Used to generate banner x ads

You do not need to use endpoints for catalog, product, customer and order syncing. Project Agora Commerce supports syncing data via file which may be suitable for larger integrators.

Content Type & Payload

The data payload is in JSON format. The Content-Type for these endpoints is application/json, which should be passed as a header in your requests:

-H "Content-Type: application/json" \

Authenticating Requests

Project Agora Commerce uses basic authentication, this should be passed as a header with your API key:

-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \

For backend integrations, you will only need the secret API key. You can locate your API key within the Project Agora Commerce Portal.

Base URLs

Project Agora Commerce uses different base URLs for staging, as well as different production environments.

Contact Project Agora Commerce to receive the staging Base URL. Production Base URLs are provided when you have completed your staging integration.

Integration Workflow

To integrate with Project Agora Commerce. You will need to integrate with our staging environment first.

Once you are successfully requesting and serving ads, as well as reporting clicks, impressions, and purchases to Project Agora Commerce, then you are ready to move to your production environment. It is best practice to discuss your launch plans with Project Agora Commerce to ensure adequate resources are allocated to your environment.

If you have specific integration requirements, please bring this to the attention of Project Agora Commerce to ensure you are integrated as efficiently as possible

Integration Summary

Integration Option One typically ensures the best end user experience and fastest results to each browser.

Adserving Summary

During ad serving:

Products are requested from the e-commerce server
Ads are requested to Project Agora Commerce
Ads are returned to the e-commerce server
The retailer merges ads with the organic product results
Ads are served to the retailer's website
Ads and organic products are shown on the website together
Impressions are reported to Project Agora Commerce
Clicks are reported to Project Agora Commerce
Purchases related to ads are reported to Project Agora Commerce

For the end user, listings are not shown until merged.

Workflow

Step 1

Customer loads e-commerce website and navigates to either a category page or a search results page.

Step 2

In the example of a customer navigating to a category page, the front end application (website) requests data from the backend server according to categories selected by the customer (e.g Computers - Notebooks).

Step 3

Retailer’s server simultaneously calls the Project Agora Commerce API and requests ads from the “Computers - Notebooks” category. *Retailer also sends customer ID (#13Xv652s) to Project Agora Commerce as part of the Ad request to ensure ads returned are relevant.

Step 4

Project Agora Commerce uses the retailer inventory (catalogue) and sales data to calculate the most relevant ads for the request (for the category and the person viewing the page). Within 50ms Project Agora Commerce will return ads to the Retailer server in the form of product code (GTIN) and URL for Banner Ads.

In case the retailer observes a big average response time, it is recommended that a timeout logic is implemented in retailer's side (where a value greater than average response time will be set as a timeout) and the page will renders without Project Agora Commerce ads.

Step 5

Retailer server sends Product Listing Ads and Banner Ad content to the front end website.

Step 6

Retailer records which ads have been viewed and clicked on within the web browser using the Project Agora Commerce Javascript SDK.

Step 7

Retailer reports any ads that have been purchased to Project Agora Commerce.

Integration Steps

Workflow

Step 1: Retailer Account initialization

Retailer sends the product feed in xml format

An important step of the retailer is to include in the product feed xml all the available categories in which each product belongs into. (1st level Parent categories, 2nd level parent categories, subcategories etc)

Project Agora imports the product feed and provides the retailers with:
- Team id
- API key
- Catalog id
- Base url
Project Agora configures test campaigns and provides retailer with snippet ad request codes

For product feed specifications, please check the following page:

Step 2: Sponsored Product Listings Integration

The SPL format is integrated in the Category, Subcategory and Search pages and it's displayed in the same grid with the organic product results.

Retailer integrates Sponsored Product Listings by following the next steps:

2.1 Request and response of an SPL:

2.2 Report clicks and impression of an SPL:

Project Agora checks the integration and confirms the success of the above process

Step 3: Discovery Sponsored Product Listings Integration

The DSPL format is integrated in the Homepage, Category, Subcategory, Search pages ,Product Pages and Cart Page and it's displayed in a separate grid from the organic product results.

Retailer integrates Sponsored Product Listings by following the next steps:

3.1 Request and response of a DSPL:

3.2 Report clicks and impression of a DSPL:

Project Agora checks the integration and confirms the success of the above process

Step 4: Orders Reporting:

Retailer integrates Orders Reporting according to the following link:

Project Agora checks the integration and confirms the success of the above process

Step 5: Static Banner integration

Retailer integrates Static Banner ads to the Homepage, Search and Category pages according to the following links:

5.1 Request and response of a Banner:

5.2 Reporting impressions and clicks for Banners:

5.3 Reporting orders for Banners:

Project Agora checks the integration and confirms the success of the above process

Step 6: Ingrid Static Banner integration

Retailer integrates Ingrid Static Banner ads to the Category, Subcategory and Search pages according to the following links:

6.1 Request and response of an Ingrid Banner:

6.2 Reporting impressions and clicks for Ingrid Banners:

6.3 Reporting orders for Ingrid Banners:

Ad Proposal file

The Project Agora Commerce Ad Proposal file is an official agreement of the positions in the retailer's website where the Project Agora Commerce formats will serve.

It depicts with detail the exact positions where the Project Agora Commerce formats will serve in all the agreed pages of the retailer's website as well as it defines the look and feel of our formats on each page.

Below there is a relevant screenshot of an ad proposal file section:

Syncing Data

Introduction

In order to generate Ads, Project Agora Commerce needs product, customer, and order data from retailers. The data needs to be populated by the retailer, then it is stored, processed, and updated in the system of Project Agora Commerce. To automate the process of downloading and updating the data, both Project Agora Commerce and each retailer need to agree on the format and structure of the data, as well as the protocol for the communication between the retailer's and Project Agora Commerce systems. This documentation describes in detail the specifications for the constraints on the feeding of three types of data: product, customer, and order data.

Syncing Data Via File Protocols

In this section, we describe the protocols that Project Agora Commerce support and how to name files so that Project Agora Commerce can download the data files automatically from the server of retailers.

Protocols

Project Agora Commerce support several ways for retrieving data files from retailers. The data files should be put on a retailer's server and the files can be downloaded via one of the standard protocols. Currently, Project Agora Commerce support downloading of data files via the below protocols: FTP, FTPS, SFTP, SCP, HTTP, HTTPS, and AWS S3. If you want to feed data files in a protocol that we have not supported yet, contact our support team.

In general, retailers will need to provide information of protocol, host, port, and the file path of a data file so that Project Agora Commerce can download it. When authentication is required to download data files, each retailer needs to provide Project Agora Commerce a credential (e.g username and password) to authenticate with the retailer's system.

In the case retailers are using SFTP protocol, Project Agora Commerce support two types of authentication to download data files from retailers. The first type of authentication is via a username and a password. The other one is via a public key. In the second type of authentication, Project Agora Commerce will provide retailers with a public key of Project Agora Commerce and the public key needs to be installed into the SFTP server of retailers.

Data Compression and Encryption

Retailers may need to compress and encrypt data before uploading the to their servers for syncing. When both compression and encryption are used on data files, Project Agora Commerce assume that the data files are compressed prior to encryption.

When a data file is encrypted, Project Agora Commerce will decrypt the data file after it is downloaded. Currently, we support data decryption for files that are encrypted by PGP programs. More information about PGP cryptography can be found at . If retailers choose to use this type of cryptography for data files, Project Agora Commerce will provide a PGP public key and retailers will the public key to encrypt data files before retailers upload the files to retailers’ servers, and only Project Agora Commerce can decrypt the encrypted data file.

When a data file is compressed, we will decompress the data file prior to processing. Currently, we support decompression of two types of compression formats. They are zip and gzip. If retailers want to support other types of format, contact our support team.

File

As previously stated, retailers will need to provide information of the protocol, host, port, and file path to a data file so that Project Agora Commerce can download and process the data file. Project Agora Commerce will download data files on daily basis. Retailers can choose a daily time when it is convenient for them to ensure that the data file is ready on the server everyday.

By default, retailers need to provide an explicit file name that Project Agora Commerce will download everyday. This is the simplest way to specify a target file. Retailers just provide a specific file name and Project Agora Commerce will use the file name to retrieve the data file from the server of retailers everyday.

When retailers use FTP, FTPS, and SFTP protocols for the communication between Project Agora Commerce and the servers of retailers, we support some other options for retailers to specify target files for Project Agora Commerce to download. The other options for the target files are ROLLING_EARLIEST, ROLLING_EARLIEST_24_HOURS, ROLLING_LATEST, and ROLLING_LATEST_24_HOURS. They are also called as target file modes that retailers can choose.

When retailers choose one of the options, they need to provide Project Agora Commerce with a textual template for the names of data files. In the textual template, there is a special string, which is “{*}”. Project Agora Commerce will use the template provided by retailers to match the file names on the server of retailers to choose and download a target file everyday.

An example of a template can be “PACommerceCatalogData_AU_{*}.txt”. The template defines that the matched file names must start with the prefix “PACommerceCatalogData_AU_” and end with the suffix “.txt”. When the template “PACommerceCatalogData_AU_{*}.txt” is used, the below file names will match with the template.

PACommerceCatalogProduct_AU_20190315.txt

PACommerceCatalogProduct_AU_20190314.txt

PACommerceCatalogProduct_AU_20190312.txt

In order to avoid downloading data files that retailers are uploading, we only download data files that have been modified more than one minute from the time we access the server. Although there are several file names match the template, we choose only one file to download and process at a time. In order to choose a file from a list of candidates, we define different target file modes that retailers can choose. Target file modes are discussed below.

Rolling_earliest

In this target file mode, we use the template to filter files by using their names. Then we sort the results by ascending file names and return the first result.

For example, if the template for file names is “CitrusCatalogData_AU_{*}.txt” and the list of file names are filtered by the template is as below, the file “CitrusCatalogProduct_AU_20190312.txt” will be chosen to download in this target file mode.

CitrusCatalogProduct_AU_20190312.txt

CitrusCatalogProduct_AU_20190313.txt

CitrusCatalogProduct_AU_20190314.txt

Rolling_earliest_24_hours

In this target file mode, we firstly use the template to filter files by using their names. Then we only choose files which are modified within recent twenty four hours. Finally, we sort the results by ascending file names and return the first result.

For example, we assume that the current time is 2019-03-15 10:30:07 and the template for file names is “CitrusCatalogData_AU_{*}.txt”. If the list of file names that are filtered by the template is in the table below, the file “CitrusCatalogProduct_AU_20190314.txt” will be chosen to download in this target file mode.

Rolling_latest

In this target file mode, we use the template to filter files by using their names. Then we sort the results by descending file names and return the first result.

For example, if the template for file names is “CitrusCatalogData_AU_{*}.txt” and the list of file names are filtered by the template is as below, the file “CitrusCatalogProduct_AU_20190314.txt” will be chosen to download in this target file mode.

CitrusCatalogProduct_AU_20190314.txt

CitrusCatalogProduct_AU_20190313.txt

CitrusCatalogProduct_AU_20190312.txt

This target file mode is similar to Rolling_earliest. However, instead of sorting the files by ascending file names, we sort them by descending file names.

Rolling_latest_24_hours

For example, we assume that the current time is 2019-03-15 10:30:07 and the template for file names is “CitrusCatalogData_AU_{*}.txt”. If the list of file names that are filtered by the template is in the table below, the file “CitrusCatalogProduct_AU_20190315.txt” will be chosen to download in this target file mode.

This target file mode is similar to Rolling_earliest_24_hours. However, instead of sorting the files by ascending file names, we sort them by descending file names.

Conclusion

We have presented how catalog product, customer, and order data, can be downloaded retailer servers and processed in Project Agora Commerce. While TSV format is supported for all data types, XML format is only supported for products. Several protocols for retrieving data files from the retailer servers are supported by Project Agora Commerce, including FTP, FTPS, SFTP, SCP, HTTP, HTTPS, and AWS S3.

Moreover, we have mentioned how we support securing data and improving the performance of downloading files via our ability to decrypt and decompress data files from retailers. To alleviate the process of feeding files and downloading from servers, we provide different options for naming files on the server. We have described the options and explained via examples in this document so that retailers can choose for their purposes.

Currently, XML format is only supported for product data. An extension of the current system in Project Agora Commerce will be completed to support the format on other types of data as well as any other new protocols or formats when there are any requirements from retailers.

You should now be ready to review how to sync catalog, customer, and order data.

Syncing Catalog & Products

You will need to create at least one catalog to integrate with Project Agora Commerce.

What Is A Catalog?

A catalog is a grouping of products and their attributes, most commonly used to group all products of an integrator's site into one single catalog.

Catalogs are selected by advertisers in the campaign creation process, their campaigns will only run within their selected catalog of products. It is common practice for all products to be grouped into a single catalog for an integrator, making selection simple for advertisers.

What Are Products?

Products are individual GTIN's on an integrator's site. Products synced with Project Agora Commerce are synced with individual identifying values and attributes. Products should represent each GTIN / SKU in your current product catalog. Products are selected by advertisers in campaign creation, only products relevant to the catalogs the advertiser selected are displayed for selection. Products should not be used to represent any more than a single product GTIN. Variations of the same product should be different products.

The SKU codes should have a prefix contained in the pa_id attribute which will be explained also in the next chapter.

pa_id is a concatenation of id with a catalog specific prefix(the catalog prefix is provided from project agora) <pa_id>=catprefix+"--"+<id> This is the universal unique id to identify each product in the pa-commerce platform. This id is used for ad requests/responses and impression/click and order reporting.

For example:

200ml, 600ml, and 2L variations of the same drink product would be regarded as 3 different products in the Project Agora Commerce.

This is commonly aligned with existing integrator practices.

Product Properties

Each product has an an individual series of properties applied to it. The filters applied to each product will depend on the quality of integration each integrator wishes to complete.

The specific terms used differentiates between syncing via API or file. Integrators are required to sync GTIN, Name,Inventory,Description andFilters. Additional properties can be used for targeting, relevancy and platform targeting features. The GTIN property can be substituted for any unique code or SKU used in the integrator's back end.

Product Filters Explained

Product filters are used in primarily in ad generation in addition to containing properties such as imageUrl and name. When requesting ads from Project Agora Commerce, you will send a context containing relevant page information, this ensures relevant ads are served to each page.

The structure of filters is up to the integrator, the most important thing to consider is that these product filters will be sent in your ad generation context. Therefore product filters should exactly match what is being requested in ad generation.

An important step of the retailer is to include in the product feed xml all the available categories in which each product belongs into into the product_type attribute. (1st level Parent categories, 2nd level parent categories, subcategories etc)

Another important step if for the retailer to include in the taxonomy attribute as described in the next section, all the available category paths in which a product belongs

A context containing productFilters:

Will only return ads for products containing all filters in the relevant array. Like below:

All the categories in ad requests should be declared with the prefix "taxonomy:" like in the example below:

Category Minimum Bid Filter Structure

There are no strict rules defining the structure of filters, it is up to integrators to define how they are structured. In the event the integrator enable category minimum bids, relevant category product filters are leveraged and mapped to a minimum bid value. It is best practice to ensure category filters are human readable to reduce confusion for advertisers creating campaigns.

If you are looking to utilize category minimum bid values, it is best to ensure categories are human readable and understandable for advertisers creating campaigns. category:Keyboards is easier to understand than category:12

Providing Image and Product Name

Project Agora Commerce needs information about product image and name to make them searchable for in the Project Agora Commerce portal when creating campaigns. These values can be sent to Project Agora Commerce inside filters formatted like:

They are seen in various areas of the Project Agora Commerce portal such as product selection below:

Syncing Catalogs & Product

You can sync your catalogs and products with Project Agora Commerce via File.

Syncing Catalog and Products Via File

XML Files

Project Agora Commerce have defined a list of tags that are used to describe an XML document for products. The table below depicts the tags and their descriptions. The tag “item” is used to describe a product in an XML document. All other tags for the other fields need to be written inside this tag. An example of a valid XML document with the tags can be seen in the below example.

<rss>
  <item>
      <id>80591011</id>
      <pa_id>catprefix--80591011</pa_id>
      <title>Melissa &amp; Doug Dinosaur Stamp Set, 4yrs+</title>
      <barcode>012345678923</barcode>
      <pa_title>Melissa &amp; Doug Dinosaur Stamp Set, 4yrs+--012345678923</pa_title>
      <description>Imagine a rugged landscape littered with volcanoes, and full of dinosaurs roaming around</description>
      <image_link>https://www.retailer.com/productImages/image1.jpg</image_link>
      <link>htttps://www.retailer.com/icecreams/melissa-dougdinosaurstam-set.html</link>
      <msrp>11.99</msrp>
      <price>9.99</price>
      <taxonomy>Dairy>Ice creams|Dairy</taxonomy>
      <product_type>Dairy>Ice creams</product_type>
      <category_path>Dairy>Ice creams</category_path>
      <availability>10</availability>
      <brand>Melissa</brand>
    </item>
    <item>
      <id>87086011</id>
      <pa_id>catprefix--87086011</pa_id>
      <title>Waitrose Splits Strawberry Ice Lollies</title>
      <barcode>789123456789</barcode>
      <pa_title>Waitrose Splits Strawberry Ice Lollies--78912345678</pa_title>
      <description>Strawberry splits; Suitable for vegetarians. Strawberry splits vanilla flavoured ice cream with a fruity strawberry ice coating. Our fundamental belief is that few things in life are more important than the food you buy. Good quality is essential.</description>
      <image_link>https://www.retailer.com/productImages/image2.jpg</image_link>
       <link>htttps://www.retailer.com/icecreams/melissa-dougdinosaurstam-set.html</link>
       <msrp>11.99</msrp>
      <price>1.25</price>
      <taxonomy>Dairy>Ice creams|Dairy</taxonomy>
      <product_type>Dairy>Ice creams</product_type>
      <category_path>Dairy>Ice creams</category_path>
      <availability>20</availability>
      <brand>Waitrose</brand>
    </item>
<rss>

The taxonomy attribute contains all the category paths in which a product belongs divided with the | sign. It is important that the different paths are divided with the | symbol without any spaces around it.

For example if a product belongs to the following categories A > B> C and D > E then all the available category paths are "A>B>C", "A>B","A" ,"D>E" and "D". The taxonomy attribute will be integrated like below:

The product_type attribute contains all the available categories (parent and current) in which a product belongs divided with the > sign

The category_path attribute contains only one indicative category path of the product. For example if the product belongs in category C which has as a parent category B and B has a parent category A, then the category_path will contain the value A > B > C

XML tags in XML documents for products

XML Tags

Required?

Description

item

Required

This tag is used to describe a product. All other XML tags for a product must be inside this tag. An XML document for products must contain a list of item tags. This field is identical to the gtin and product_code fields in API and TSV file syncing.

Required

This tag is to describe a unique code to identify a product in the system of retailer.

pa_id

Required

The pa_id is a concatenation of id with a catalog specific prefix(the catalog prefix is provided from project agora) <pa_id>=catprefix+"--"+<id> This is the universal unique id to identify each product in the pa-commerce platform. This id is used for ad requests/responses and impression/click and order reporting.

title

Required

This tag is to describe the name of a product.

barcode

Required

The barcode/GTIN of the product

pa_title

Required

The pa_title is a concatenation of the title of the product and the barcode. <pa_title>=<title>+"--"+<barcode>.

description

Required

This tag is to describe a description of a product.

image_link

Required

This tag is to describe the hyperlink to an image of a product.

If the value is provided, it must be a valid URL. The syntax of a URL can be found at http://www.ietf.org/rfc/rfc2396.txt

link

Required

The landing page url of this item (product details page). If this product has multiple product details pages (because it exists in multiple different categories), please select a random one.

msrp

Required

Manufacturer's Suggested Retail Price: Price before discount including VAT

price

Required

This tag is to describe the price of a product. If the value inside the tag is provided, it must be a number.

taxonomy

Required

This tag is to describe all the available category paths for this product

product_type

Required

This tag is to describe the category hierarchy of a product.

product_type_code

Optional

This tag is to describe filters on the product. If the value is provided, it must be a json array.

For example:

<product_type_code>[“brand_name:green-fairy", "category:absinthe", "department:spirits", "productName:Green Fairy Absinth Gift Pack 500mL", "varietal:absinthe", "webcountryoforigin:czech-republic"]</product_type_code>

category_path

Required

This tag contains one indicative hierarchy of the product's category tree

brand

Required

This tag is to describe the brand of the product

availability

Required

This tag is to describe the inventory of a product. The value must be a number. If the product is out of stock it should have the value 0

The retailer has to ensure that every product is included in the xml file even if the product is out of stock.

The <pa_id> and <pa_title> were introduced on April 2020 as part of the new pa commerce integration process.

Syncing Order Data

Why Sync Order Data

Project Agora Commerce requires order data generate relevant ads and to disburse money properly to all entities involved in transactions (disbursement occurs only in the case of discounts. Project Agora Commerce charges only for impressions and clicks.).

Syncing orders is also valuable for advertiser and retailer dashboards in the Project Agora Commerce portal. Orders are used in sales, conversion, sale value and ROAS calculations. These are invaluable for advertiser teams to gauge their investment worth, and contribute additional spend.

Order Attribution Options

Project Agora Commerce supports the following option to attribute ads to orders.

Attribution Option: sessionId Attribution

This method shares attribution responsibility between the integrator and Project Agora Commerce. Project Agora Commerce is responsible for linking any adId served to the sessionId and then to the relevant products purchased.

sessionId Overview

A sessionId is an identifier for an individual user's session. Some integrators may refer to it as a cookie Id. This sessionId can be generated solely for Project Agora Commerce or have an existing cookie Id for a single session substituted as the sessionId value.

The sessionId must be generated for each single session.

When requesting ads, integrators send the sessionId in the context, such as below:

When submitting orders, the same sessionId needs to be communicated when a relevant order is submitted. This spares the integrator from the work required to store each adId. In an API push, the field is within the orders object:

The whole request should look like below:

Here is a mock example:

If successful, you will get the following object returned:

The gtin field should contain the respective pa-id for this product, the quantity field should contain the quantity of the product that was ordered, and the reqularUnitPrice andtotalOrderItemPriceAfterDiscounts should contain both the final price of the product as exists in the product feed.

The retailer should sent to PA Commerce all the orders being made to his website(even the ones that don't include SPL/DSPL or products related with Static Banner campaigns) and Project Agora Commerce is responsible to detect the orders that include SPL/DSPL or Static Banner related products and make the proper attribution. Those orders will only be shown in the client's dashboard of the Project Agora Commerce platform.

If the integrator expire, rotate, or lose sessionId data between ad serving and order submission, there is no way for Project Agora Commerce to attribute orders. The sessionId submitted with orders must be identical to the sessionId sent in ad requests.

The gtin field in orderItems element above is the <pa_id> of this product

Some finals points that need to be taking care of regarding sessionId order attribution:

the sessionId sent in the ad request and the one in the order attribution should be the same
An ad should have received an impression and click in order to be properly attributed in an order
Time between requesting an ad and the order/purchase is less or equal to the attribution window (which is 2 days)
Ideally the value chosen to be sessionId needs to be unique per user and the same for different user sessions
All orders being made to the website should be sent in the order ad request as order objects and Project Agora Commerce will attribute the ones related with Project Agora Commerce formats.

Syncing Multiple Orders

Sending Order Data to Project Agora Commerce

To send multiple order data to Project Agora Commerce, use a command similar to the command below. Note that the data in the "orders" field below is dummy data and is provided here only as an example

Multiple orders

In case you want to send multiple different orders you will have to separate them like different objects inside the "order" object

For multiple orders (for example for two different sessionIds) the context would be the below:

{
    "orders": [
       {
        "orderDate": "2019-12-02T15:00:00Z",
        "sessionId": "23dn3923-323d",
        "orderItems": [
            {
                  "gtin": "9891998566P",
                  "quantity": 5,
                  "regularUnitPrice": "1.00",
                  "totalOrderItemPriceAfterDiscounts": "5.00"
                }
              ]
            },
                {
        "orderDate": "2019-12-02T15:07:05Z",
        "sessionId": "27on8827-679d",
        "orderItems": [
            {
                  "gtin": "9891998566P",
                  "quantity": 5,
                  "regularUnitPrice": "1.00",
                  "totalOrderItemPriceAfterDiscounts": "5.00"
                }
              ]
            }   
    ]
}

Relevant Context Fields

String

Description

Required?

adId

The ad ID. This field should be populated if this order item has been bought as a result of a view or click on an ad.

Optional

citrusDiscountAmount

The amount of the Project Agora Commerce discount that was applied to the ad. The application to an ad of both a discount amount and additional constraints can cause the Project Agora Commerce discount value to be less than the maximum value of the original ad.

Required for Discounts

gtin

This is the pa_id as used in the xml product feed (catprefix--"SKU").

Required

This is the Id of the order you are pushing to Project Agora Commerce. Can be populated with the order Id maintained in the integrator's system. If no value is provided, one will be generated in the returned object.

Optional

sessionId

This is a generated id that you control that identifies a user's session. Project Agora Commerce can use this for purchase attribution.

Required

orderDate

The date of the order. Required in ISO format.

Required

orderItems

The items included in the order being pushed to Project Agora Commerce.

Required

quantity

The number of the gtin purchased

Required

regularUnitPrice

The regular price of the item added to cart

Required

teamId

Your retailer teamId, this is used to identify the orders are coming from your team. Can be deduced from the API key.

Optional

totalOrderItemPriceAfterDiscounts

The whole order item price after all applicable discounts are applied, including the Project Agora Commerce discount.

Required

your_api_key_here

Your API key

Required

For a glossary of all terms in the documentation, see the reference.

The "gtin" fields in the "orderItems" object should be filled with the "pa-id" fields taken from the responses of an SPL, DSPL or Banner request and in the cases of the site's organic products (not belonging in the Project Agora Commerce formats) they should be filled with the respective "pa-id" values taken from the product feed for those products.

It is important to save the value of "pa-id" in each step so as to use it in a later stage when sending the order object with the API

Reporting Clicks and Impressions

This document explains how to report impressions and clicks using Epsilon Retail Media APIs, with steps for integration and improved ad ID validation.

You will need to get your Base URL from Project Agora Commerce before you are able to report impressions and clicks to CitrusAd.

Reporting clicks and impressions can take up to one hour on our staging environment. This is not reflective of production speed and should not be regarded as such.

To effectively report impressions and clicks, use /resource/ endpoint. Impressions should be directed to the first-i resource, while clicks should be reported to the second-c resource.

Prerequisite

Obtain your Base URL from your Technical Account Manager before reporting impressions and clicks.

Integrating Endpoint Calls

Endpoint calls must be executed within your app or website. In Project Agora E-Commerce, the integration process is similar for both mobile apps and websites due to its 'backend to backend' integration approach. This approach ensures that ad requests are consistent across both desktop and mobile platforms. However, since mobile apps do not support JS libraries, you must make backend requests to our click and impression endpoints.

Reporting Impressions

To report an impression, send a GET request in the following format:

Text

https://$BASE_URL.citrusad.com/v1/resource/first-i/AD_ID

Replace AD_ID with the adId provided for the ad you are reporting.

For example, the following GET request reports an impression for the adId, display_xw3ybbrymHT_D3VwU3Ic5ThUkbhFNkY4NVNIODU4NEVGRkdT.

Text

https://$BASE_URL.citrusad.com/v1/resource/first-i/display_xw3ybbrymHT_D3VwU3Ic5ThUkbhFNkY4NVNIODU4NEVGRkdT

Reporting Clicks

To report a click, send a GET request in the format below:

Text

https://$BASE_URL.citrusad.com/v1/resource/second-c/AD_ID

Replace AD_ID with the adId provided for the ad you are reporting.

For example, the following GET request reports an impression for the adId, display_xw3ybbrymHT_D3VwU3Ic5ThUkbhFNkY4NVNIODU4NEVGRkdT.

Text

https://$BASE_URL.citrusad.com/v1/resource/second-c/display_xw3ybbrymHT_D3VwU3Ic5ThUkbhFNkY4NVNIODU4NEVGRkdT

API Validation for Realized Ad IDs

The API includes validation for ad IDs to ensure accurate data and reduce errors. Requests with improperly encoded or prefixed ad IDs return a 400 error and a detailed error message.

Key Benefits

Faster Issue Resolution: Quick feedback helps retailers fix problems faster.
Better Accuracy: Fewer errors mean more accurate reports and data.

Example Error Message

"Invalid ad ID. Must be properly encoded and prefixed with 'display', 'banner', or 'shotgun_'."

INTEGRATION GUIDES

HTTP Persistence & Ad Caching

HTTP Persistence Guide

Project Agora Commerce requires a persistent HTTP connection in order to speedily respond to Ad Generation requests. Ad Generation requests should be made on a persistent connection (and not have a new connection generated every time a new Ad Generation request is made) in order for you to receive Project Agora's Ad services at the intended speed.

Every TLS handshake that is generated has a cost, and the more TLS handshakes that are established, the more expensive is the transfer of data from Project Agora Commerce to your E-commerce website.

Maintaining a persistent HTTP connection avoids congestion and improves HTTP response times.

To learn more about HTTP persistent connections, see the following resources:

Ad Caching Guide

Ads returned from Ad Generation Endpoints regardless of adtype cannot be cached.

Every time a page is loaded on a retailer's website, a new ad generation request should be sent to Project Agora Commerce with the correct context, to generate a fresh set of ads.

Reference

Field Descriptions

String

Description

Required or Optional

adId

The Ad ID. This field should be populated if this order item has been bought as a result of a click on an ad.

Optional

adIds

The Ad IDs. This field should be populated if an explicit association between order items and ad ids can't be provided. This field is used to provide the association at order level.

Optional

Api Key

This is your Api Key. Your Api Key is used to identify and authorise the Retailer team.

Required

bannerSlotIds

This defines the ids of the Banner Ads slots that are available on the retailer website. Banner Ad slots are defined in content standards. Content standards are provided by retailers.

Required for Banner Ads

catalogs

The catalogs being created

Required

catalogId

The id of the catalog the product belongs to. This is required to bind a product to a catalog.

Required

placement

This is a required variable for all kind of requests. It defines the type of the request

Required

citrusDiscountAmount

The amount of the Citrus discount that was applied to the ad. The application to an ad of both a discount amount and additional constraints can cause the Citrus discount value to be less than the maximum value of the original ad.

Required for Discounts

contentStandardId

Defines the content standard to use in Banner Ad generation.

Required for Banner & Email Ads

context

The context of the ad served

Required

currentCartItems

This field is populated with information about items that the user has already added to their cart.

Required for Sample, Substitution, and Discount campaigns

customerId

The id of the customer that has created the order.

Optional

groups

A list of traits of the product. Must be human readable Can be things such as: brand, category, style, demographic, ect.

Optional

GTIN

Global Trade Item Number. A globally-unique 14-digit number used to identify trade items.

This can be substituted for any unique code or SKU used in your back end.

Required

filters

filters associated with the request

Required

This is the ID of the content you are pushing to Project Agora Commerce. This can be a catalog id or order id.

This is individual to each individual item pushed.

N/A

inventory

The number of available items of this product.

Optional

imageUrl

The URL of the image of the product

Required

maxNumberOfAds

This is the maximum number of ads that Project Agora Commerce generates. If advertisers have not provided enough requests for ad placements, the number of ads provided will not reach the number defined here. Must be greater than 0.

Required

name

The name of your catalog. If you are importing multiple catalogs your advertisers will be able to see these catalog names when creating campaigns

Required

orderDate

The date of the order.

Required

orderItems

The items included in the order being pushed to Project Agora Commerce

Required

orders

The type of object being pushed to Project Agora Commerce. In this case it is orders

N/A

pageType

This field determines the type of ad that is to be returned. Home, Category, Search, and Specials fall into the display ad category which is applicable when user is browsing the website and looking for products to add to cart.

Required

Price

The price of the product

Required

productFilters

This field is optional. This is an array of string arrays that includes product filter ids previously sent to Project Agora Commerce when catalog product information was sent to Project Agora Commerce. This makes it possible for the ad requester to narrow down the ads returned so that the ads that are returned are only the ones that match the filter.

An example of a filter is [["a", "b"], ["c", "d"]] or (a && b) || (c && d). These can be interpreted as ("A and B or C and D").

Optional, depending upon pageType. If the pageType is category, this is required.

productName

The name of the product.

Required

profit

Typical monetary profit of the product

Optional

quantity

The quantity of the product purchased

Required

regularUnitPrice

The regular price of the item added to cart

Required

searchTerm

The search term entered by the customer. This is used for filtering purposes.

Required

sessionId

This is a generated id that you control that identifies a user's session. Project Agora Commerce can use this for purchase attribution.

Optional

substitutedFor

The GTIN of the product that the item was substituted for.

Required for Substitutions

substitutedProductGtin

If the pageType is "substitutions", this field is mandatory. If the product is being substituted in the picking process, this product identifier should be provided so that you can receive ads for the replacement product.

Optional

Groups Explained

Groups are applied to a catalog product. They specify traits about products that advertisers can use to create campaigns against groups of products, rather than specific products. They must be human readable. Groups could be things like: brand, category, style, demographic, etc.

An example of this would be a specific product range that share a similar trait. Such as a pair of basketball and running shoes still under the same specific product range.

{
            "gtin": "productStyle1-Basketball",
            "groups": [
                "Brand",
                "Shoes",
                "Mens",
                "ProductRangeName",
                "Basketball"
            ]
}
{
            "gtin": "productStyle2-Running",
            "groups": [
                "Brand",
                "Shoes",
                "Mens",
                "ProductRangeName",
                "Running"
            ]
}

When creating a campaign, advertisers would then be able to specify that they want to create ads for all products that match those groups. e.g. "Brand", "Shoes", "Running" would create ads for the productStyle2-Running product, but not the productStyle1-Basketballproduct. This becomes powerful if an advertiser wishes to create ads for their entire shoe collection, they could select the groups for their brand, and their shoes. In the above example, they would select: "Brand", "Shoes".

Requesting Ads (the "Context" and its Parts)

What Is A Context?

In order to request ads, you must provide a context. A context is a set of filters that ad campaigns must be eligible for before they are shown.

A Context is what ensures ads remain relevant, this is because ads must meet each of the defined filters of the context before being shown.

On this page, contexts for Product Ads are displayed.

Before you request ads, you will need your catalogIdand yourapi key.

A Simple Search Context

A simple context can be used as an example. Below is a simple context for a search page:

For an ad to be eligible for this context, it must:

Have the catalog selected with the displayed catalogId
Target the search term Wine

Each context is made of various relevant parts, each of the above can be viewed in the page reference at the end of the page.

A Filtered Search Context

When a user filters their browsing deeper, you are able to serve ads relevant to their filters using productFilters in the context.

In this example, the user has navigated to the Red Wine category within their search, and filtered their browsing to to "Shiraz" Red Wines. This is a new request and considered by Project Agora Commerce as a new page, and new set of ads. Even in the rare event the ads served are identical to the unfiltered results.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["taxonomy:RedWine>Shiraz"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["taxonomy:RedWine>Shiraz"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}

For an ad to be eligible for this context, it must:

Have the catalog selected with the displayed catalogId
Target the search term Wine
Be a product with the productFilters of category:RedWine and category:Shiraz

For more information on product filters, see the "Syncing Catalog & Products" page:

A Simple Category Context

A simple context can be used as an example. Category pages use productFilters to match product properties to each page. Below is a simple context for a category page:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:RedWine"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}

-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:RedWine"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}'

For an ad to be eligible for this context, it must:

Have the catalog selected with the displayed catalogId
Be a product with the productFilters of the category Redwine

Each context is made of various relevant parts, each of the above can be viewed in the page reference at the end of the page.

A Further Filtered Category Context

When a user filters their browsing deeper, you are able to serve ads relevant to their filters using productFilters in the context.

In this example, the user has entered the Red Wine category, filtered their browsing to to "Shiraz" Red Wines and selected the "Australian" type. This is a new request and considered by Project Agora Commerce as a new page, and new set of ads. Even in the rare event the ads served are identical to the unfiltered results.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:RedWine>Shiraz", "filter:Australian"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:RedWine>Shiraz", "filter:Australian"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}'

For an ad to be eligible for this context, it must:

Have the catalog selected with the displayed catalogId
Be a product with the productFilters of categories Redwine and subcategory Shiraz and type:Australian

For more information on product filters, see the "Syncing Catalog & Products" page

sessionId is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page

Product Listing Ad Integration Guide

How to integrate to serve Product Listing Ads

Product Listing Ads are typically the easiest to integrate and request for retailers due to the ease of integration.

Are You Ready to Request Product Listing Ads?

This guide assumes you have already created your catalog, created your products, and are sending customer and order data to Project Agora Commerce.

The Product Listing Ad Context

In order to request Product Listing Ads, you must provide a context. See "The Product Listing Ad Context" for more information.

Recommended Sponsored Product Listing Style

Requesting a Category Product Ad

Page Category ads require a simple "context' to be sent to Project Agora Commerce. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.

Minimum Viable Context:

Below are the minimum values needed to generate a category ad:

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_here" \
-d \
'{
    "catalogId": "$MY_CATALOG_ID",
    "productFilters": [
      ["taxonomy:string"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": number,
    "sessionId": "string"
}'

Exemplar Context

Here is an example of a context:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:computers"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:computers"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP/2 200
{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516953955Z"
        }
    ],
    "banners": [],
    "products": []
}

{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516953955Z"
        }
    ],
    "banners": [],
    "products": []
}

No customer information or cart items are necessary in this simple context. The simple context consists only of necessary filters.

In each category page the SPL requests should include in one filter the whole category path leading to this page as described also in the taxonomy attribute of the product feed. For instance if category C belongs to category B and B belongs to A, the category path is A > B > C, then the SPL request for the page C should have this filtering:

"productFilters": [
      ["taxonomy:A>B>C"]
    ],

The SPL for category page B would be:

"productFilters": [
      ["taxonomy:A>B"]
    ],

The discount and products fields are legacy and can be ignored

The placementsponsoredproducts should be included in all SPL requests

In gtin field of the above responses you will get the pa_id as in the product feed for the product to be displayed.

Reminder: the pa_id is the concatenation of the catalog prefix and each product SKU, so to identify which SKU to display on your side you may need to remove the catalog prefix and the symbols "--"

pa_id= catprefix

Position Attribute in response

When you receive in the response of one SPL request the attribute position, please note that this declares the order in which this SPL ad should be placed in the SPL grid.

For example if in the response you get the below:

"position": 1

then you shall serve the ad coming from this response in the first position of the SPL items.

Filtered Browsing

When a user filters browsing deeper into subcategories, you are able to serve ads relevant to their filters using more productFilters in the context.

In this example, the user has navigated to the Computers category, and browsed further to "Laptops" and "Windows" categories. This is a new request and considered by Project Agora Commerce as a new page, and new set of ads. Even in the rare event the ads served are identical to the unfiltered results.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:computers>Laptops>Windows"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:computers>Laptops>Windows"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}'

As your customers filter deeper in their searches, your request will include more product filters

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:computers>Laptops>Windows", "delivery:DeliveryOnly", "pricerange:$250-$500"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:computers>Laptops>Windows", "delivery:DeliveryOnly", "pricerange:$250-$500"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP/2 200
{
    "ads": [
       {
            "id": "display_ZFwfo0Mi2AhFBxUBHpXnICvV2j8zNTcxNzExUA==",
            "gtin": "catpref--3571711P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936105529Z"
        },
        {
            "id": "display_VpFfnPOnaG4MZh43ckQjufmGAzwzNTcxOTkyUA==",
            "gtin": "catpref--3571992P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936111787Z"
        },
        {
            "id": "display_vRHRnkTXbbssVwiem8jDrmOp2FM2Mzg3NTkyUA==",
            "gtin": "catpref--6387592P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936117921Z"
        },
    ],
    "banners": [],
    "products": []
}

{
    "ads": [
       {
            "id": "display_ZFwfo0Mi2AhFBxUBHpXnICvV2j8zNTcxNzExUA==",
            "gtin": "catpref--3571711P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936105529Z"
        },
        {
            "id": "display_VpFfnPOnaG4MZh43ckQjufmGAzwzNTcxOTkyUA==",
            "gtin": "catpref--3571992P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936111787Z"
        },
        {
            "id": "display_vRHRnkTXbbssVwiem8jDrmOp2FM2Mzg3NTkyUA==",
            "gtin": "catpref--6387592P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936117921Z"
        },
    ],
    "banners": [],
    "products": []
}

The most common case of a filtered request concerns the brand filter.

Specifically when a user navigates to a category page and chooses a brand filter (usually from a left menu), then a new ad request shall take place as above while the SPL items from the category request before choosing the filter shall be hidden.

For example in case the user navigates to the category Computers>Laptops then the new ad request after the user chooses the filter Topbrand shall have the following productFilters:

"productFilters": [
      ["taxonomy:Computers>Laptops",brand:Topbrand"]
    ],

Brand page Request

Kindly note that the process for requesting an SPL ad inside a brand/vendor page is exactly the same except from the Product Filtering which changes like this:

"productFilters": [
      ["brand:brand_name","placement:Brand-Page"]
    ],

where brand_name is the exact name of the brand as indicated in the product feed.

In case there is a category filtering menu on a brand page, then when a user chooses a certain category as a filter, the respective category shall be added in the ad request.

For example if the category "Face" which is a subcategory of "Woman" is chosen by a user then the ad request in this brand page will contain the following product filter:

"productFilters": [
      ["brand:brand_name","taxonomy:Woman>Face","placement:Brand-Page"]
    ],

Multiple Brand Filters in Category Pages

When a brand menu is available as a filtering option in the category pages of the website, then the SPL requests shall respond according to the user input (the option that he will choose from the menu) and the rendering of the SPL grid should be handled by new SPL requests.

If multiple options are selected from the menu then the request shall be handled as in the below example.

In this example the user is navigating in the category page Woman > Face and he chooses as a filter the brands "brand1" and "brand2"

"productFilters": [
      ["brand:brand1","taxonomy:Woman>Face","placement:Brand-Page"],["brand:brand2","taxonomy:Woman>Face","placement:Brand-Page"]
    ],

Please note that two attributes separated with the "," character inside brackets [], are handled with an OR logic while the character "," outside the brackets, is connected among different objects with the AND logic.

In the above example, the request translates as: render an SPL item belonging in the category Woman > Face and with brand1 OR render an SPL item belonging in the category Woman > Face and with brand2

sessionId is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page

If you are unsure of the strings displayed on this page. Take a look at the Reference page.

SPL items when Sorting is used

Please note that when the user chooses the option to sort the products on the website, the page should be rendered without showing any SPL item so that there won't be any disruption on the sorting functionality and user experience

Enabling Google Analytics tracking for SPL items

In order to start having recordings in your Google Analytics account for the SPL items you will have to add the following utm parameter in the landing url of an SPL item:

utm_source=pacommerce&utm_medium=spl

Requesting a Search Term Product Ad

Search term ads are typically the easiest to request. They require a simple "context' to be sent to Project Agora Commerce. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.

Minimum Viable Context:

Below are the minimum values needed to generate a search term ad:

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_here" \
-d \
'{
    "catalogId": "$MY_CATALOG_ID",
    "searchTerm": "string",
    "placement": "sponsoredproducts",
    "maxNumberOfAds": number,
     "sessionId": "string"
}'

Exemplar Context

Here is an example of a context for the pageType "Search":

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
     "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP/2 200
{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516953955Z"
        }
    ],
    "banners": [],
    "products": []
}

"ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516953955Z"
        }
    ],
    "banners": [],
    "products": []
}

No customer information or cart items are necessary in this simple context. The simple context consists only of search terms and necessary filters.

In order to properly integrate the Search Term Product Listing ad request the searchTerm value shall contain a variable which is used in the search bar of the website's search page and is filled by user input.

This ensures that the ad request is being executed in every case with the value that users enters in the search bar, so that relative ads will show up.

The discount and products fields are legacy and can be ignored

The placementsponsoredproducts should be included in all SPL requests

In gtin field of the above responses you will get the pa_id as in the product feed for the product to be displayed.

pa_id= catprefix--SKU

Filtered Searches

When a user filters their browsing deeper, you are able to serve ads relevant to their filters using productFilters in the context.

In this example, the user has navigated to the Red Wine category within their search, and filtered their browsing to "Shiraz" Red Wines. This is a new request and considered by Project Agora Commerce as a new page, and new set of ads. Even in the rare event the ads served are identical to the unfiltered results.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["taxonomy:RedWine>Shiraz"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
     "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["taxonomy:RedWine>Shiraz"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
     "sessionId": "23dn3923-323d"
}'

As your customers filter deeper in their searches, your request will include more product filters

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
       ["taxonomy:RedWine>Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
     "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
       ["taxonomy:RedWine>Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
     "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP/2 200
{
    "ads": [
       {
            "id": "display_ZFwfo0Mi2AhFBxUBHpXnICvV2j8zNTcxNzExUA==",
            "gtin": "catpref--3571711P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936105529Z"
        },
        {
            "id": "display_VpFfnPOnaG4MZh43ckQjufmGAzwzNTcxOTkyUA==",
            "gtin": "catpref--3571992P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936111787Z"
        },
        {
            "id": "display_vRHRnkTXbbssVwiem8jDrmOp2FM2Mzg3NTkyUA==",
            "gtin": "catpref--6387592P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936117921Z"
        },
    ],
    "banners": [],
    "products": []
}

{
    "ads": [
       {
            "id": "display_ZFwfo0Mi2AhFBxUBHpXnICvV2j8zNTcxNzExUA==",
            "gtin": "catpref--3571711P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936105529Z"
        },
        {
            "id": "display_VpFfnPOnaG4MZh43ckQjufmGAzwzNTcxOTkyUA==",
            "gtin": "catpref--3571992P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936111787Z"
        },
        {
            "id": "display_vRHRnkTXbbssVwiem8jDrmOp2FM2Mzg3NTkyUA==",
            "gtin": "catpref--6387592P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936117921Z"
        },
    ],
    "banners": [],
    "products": []
}

Filtered Search with Brands

When a brand menu is available as a filtering option in the search page of the website, then the SPL requests shall respond according to the user input (the option that he will choose from the menu) and the rendering of the SPL grid should be handled by new SPL requests.

If multiple options are selected from the menu then the request shall be handled as in the below example.

In this example the user is navigating in the search page with the search term "Wine" and he chooses as a filter the brands "brand1" and "brand2""

"searchTerm": "Wine"
"productFilters": [
      ["brand:brand1"],["brand:brand2"]
    ],

In the above example, the request translates as: render an SPL item coming from a search query with the search term "Wine" which belongs to either one from the brands "brand1" and "brand2"

The above query can be enhanced further with a category filter. For example there might be a category menu also in the search page which narrows down the results of the search query.

In that case if for example the category "Woman>Face" was chosen by the user then the body of the request shall be modified as below:

"searchTerm": "Wine"
"productFilters": [
      ["brand:brand1","taxonomy:Woman>Face"],["brand:brand2","taxonomy:Woman>Face"]
    ],

SPL items when Sorting is used

Enabling Google Analytics tracking for SPL items

In order to start having recordings in your Google Analytics account for the SPL items you will have to add the following utm parameter in the landing url of an SPL item:

utm_source=pacommerce&utm_medium=spl

sessionId is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page

If you are unsure of the strings displayed on this page. Take a look at the Reference page.

Discovery Product Listing Ad Integration Guide

How to integrate to serve Discovery Product Listing Ads οn:

Homepage
Category/Subcategory page
Search page
Product details page
Checkout page

Are You Ready to Request Discovery Product Listing Ads?

This guide assumes you have already created your catalog, created your products, and are sending customer and order data to Project Agora Commerce.

The Discovery Product Listing Ad Context

In order to request Discovery Product Listing Ads, you must provide a context. See "The Discovery Product Listing Ad Context" for more information.

Recommended Discovery Sponsored Product Listing Style

The Discovery Product Listing Ads are usually integrated as ad positions inside a grid which is agreed with the client according to the ad proposal document.

This grid is called the Discovery Grid.

Requesting a Discovery Product Ad

Discovery ads require a simple "context' to be sent to Project Agora Commerce. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.

All Discovery ads use the following static filters:

"placement": "Discovery-Home" for homepage
"placement": "Discovery-Category" for category/subcategory pages
"placement": "Discovery-Search" for search page
"placement": "Discovery-Product" for product detail page
"placement": "Discovery-Checkout" for checkout page

The placement value used for Discovery ads is "discoveryproducts"

Homepage: Minimum Viable Context

Below are the minimum values needed to generate a Discovery homepage ad:

Homepage: Minimum Exemplar Context

Here is an example of a context for requesting a Discovery homepage ad:

When you successfully request an ad, you receive the following object:

Search Page and Checkout/Cart Page

For the "Checkout/Cart page" and the "Search page" the request and responses are exactly the same as in the case of Homepage Discovery Sponsored Listings as shown above with the only difference that the productFilters attribute changes to "placement": "Discovery-Checkout" and "placement": "Discovery-Search" respectively.

The placement attribute is the same for all Discovery ad types: "discoveryproducts"

Category Page

In the case of the Category/Subcategory pages there are two ad requests that should take place and the results that will be displayed in the page is the merge of those two requests.

1st Ad request

Specifically the first ad request should be executed like below:

The string parameter inside the productFilters attribute shall contain only the first-level parent category of the category path in which the specific category of the category page belongs and the static filter placement:Discovery-Category.

For example the ad request inside the category Cream which has the below category path: Woman>Face>Cream (the first parent category is "Woman") should be like this:

When you successfully request an ad, you receive the following object:

2nd Ad request

The second ad request should be executed like below:

This request as seen above will have only the placementdiscovery-category as in the case of the homepage, checkout and search page DSPL requests (with their respective placements).

Merging results

The final part is to merge the above responses in order to populate the Discovery Sponsored Product Listings positions inside the Discovery grid.

Specifically all the positions inside the Discovery Grid should be populated with the ad responses that you have get from the 1st ad request .

In case there are no ad responses for the 1st ad request, the positions of the Discovery Grid shall be populated with the responses from the 2nd ad request.

In addition if there are not enough ad responses to fill all the agreed positions( from the ad proposal) in the Discovery Grid from the 1st ad request then the rest of the positions will have to be populated with the responses from the 2nd ad request.

Please note that in case there are duplicate ad responses from the 1st and 2nd ad requests (as the 2nd request is more generic and may contain also items which are included in the 1st one too) we want to serve them only once.

Example

For example in case in the category page according to the ad proposal 8 positions should be filled with DSPL ads in the Discovery Grid, then the 1st ad request should be made and the 2nd one with maxNumberOfads:8

In case the 1st ad response will return only 3 items, then the first three items of the Discovery Grid shall be populated with the 3 items of the 1st ad response while the remaining 5 with the items returned as a response from the 2nd ad response

Product details Page

In the case of the Product details pages there are two ad requests that should take place and the results that will be displayed in the page is the merge of those two requests.

The process is exactly the same as described above in the Category/Subcategory with the only change of the productFilters sttic filter used in the request which will now be: "placement": "Discovery-Product"

Keep in mind that in the 1st ad request, the first level parent category of the category path in which this product belongs should be included in the request.

Position Attribute in response

When you receive in the response of one DSPL request the attribute position, please note that this declares the order in which this DSPL ad should be placed in the DSPL grid.

For example if in the response you get the below:

"position": 1

then you shall serve the ad coming from this response in the first position of the DSPL items.

No DSPL responses case

An important note for the cases there are no Discovery Product Listings items in response of the DSPL ad requests:

For the cases when there is no discovery sponsored listing ad to serve (because of no active campaigns), you will have to fill the positions in the discovery grid with organic items and remove the sponsored labeling. It is also important to make a check to your organic items and not show any out of stock products inside the grid

Enabling Google Analytics tracking for DSPL items

In order to start having recordings in your Google Analytics account for the DSPL items you will have to add the following utm parameter in the landing url of a DSPL item:

sessionId is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page

Banner Ad Integration Guide

Overview

The Banner Ad Integration Guide explains what a retailer must provide in order to serve Banner Ads. Project Agora Commerce generates Banner Ads in the same way that Project Agora Commerce serves Product Listing Ads. Retailers have control of generated banners.

Integration Process

The following steps on Project Agora Commerce side will be completed within the Project Agora Commerce staging environment. Once everything is working correctly, you will then be ready for production. The integration process for Banner Ads is typically straightforward:

Provide necessary data to Project Agora Commerce to generate your content standard
Your content standard will be sent for approval
Once approved, your content standard will be loaded into your namespace and your content standard ID will be generated
You are ready to request Banner Ads

Are You Ready to Request Banner Ads?

This guide assumes you have already created your catalog, created your products, and are sending customer and order data to Project Agora Commerce.

The Banner Ad Context

In order to request Banner Ads, you must provide a context. See "The Banner Ad Context" for more information.

Please note that Banner ads responses will be displayed in the banners array while Product Listing and Discovery Product Listings are displayed inside the ads array as seen in the next sections.

Banner Ad Content Standard

In order to make it possible for advertisers to place Banner Ads on a retailer's e-commerce site, a content standard is needed. Content standards define what conditions must be met for the creative that advertisers create and upload.

Below is an example of a content standard page that defines a Banner Ad slot on an example retailer website. The Banner Ad slot in this instance (Category / Search) is located at the top of the website sub category page above the first row of product tiles.

An example of a content standard, which defines to the supplier, which page type (category or search page) the Banner Ad will appear on and the location of the Banner Ad within that page.

Once you have defined the rules around how Banner Ads should look on your website and where they will appear throughout your website, Banner Ads will appear in your admin console for approval before they become part of the dynamic auctions that are available to advertisers to bid on.

When you (the retailer) have defined your content standard, advertisers will provide content to fill the slots, which you will then use the Project Agora Commerce interface to approve for inclusion on your e-commerce website. How to Define a Content Standard and Share it with Project Agora Commerce.

This section explains how a retailer defines a content standard and provides the content standard to Project Agora Commerce so that Banner Ads can be made available to advertisers.

Example Content Standard

The content standard is the list of all slots on your website and their attributes. These attributes include the width and height of the Banner Ad, supported image types, specific Banner Ad rules, guidelines for any branding or use of color within the Banner Ad and the slot id of the Banner Ad. Each Banner Ad location on your website is known as a "slot", and each slot has a unique "slot id".

Multiple page types can host the same "slot" depending on your integration. An example of this would be a "category" Banner Ad. This could be hosted on multiple category levels within your site.

Providing Content Standard Data to Project Agora Commerce

To create your content standard you will need to provide Project Agora Commerce appropriate details about your website. This should be screenshots or links to pages of your website with the information in the section below called "Necessary Fields in the Content Standard". Project Agora Commerce will then convert your content standard into code that will make your Banner Ad slots available for real-time auction to advertisers.

If you are unsure what pages and positions to serve Banner Ads, contact Project Agora Commerce for our opinion on where to serve Banner Ads to best monetize your website.

Necessary Fields in the Content Standard

You (the retailer) must provide the following parameters in the fields of the content standard:

Banner Ad information:

Width of the Banner Ad (for example, 2000px)
Height of the Banner Ad (for example, 300px)
Image type of the art in the Banner Ad (for example, PNG)
Slot id of the Banner Ad -- this should be unique, with no spaces. It should be human-readable and variable-name safe. For example, "homepage_desktop_1", "homepage_mobile_1", "HomePageDesktop1", and "HomepageMobile1" are all acceptable values. Spaces are not permitted. "Home page desktop 1" is not an acceptable slot id for a Banner Ad.

Design Rules for the Banner Ad -- (example rules)

Banner Ads must have the background color #F2F2F2
Banner Ads must use the "Open Sans Light" font for any text.
Banner Ads must contain your company logo
Banner Ads must not contain more than 40 characters of text
Banner Ads must not be more than 40% covered in color, branding or product images

Banner Ad Definition Examples

Category Banner Ad:

Product Tile Banner Ad:

Example Retailer Slot Rules

An example of rules to be sent to Project Agora Commerce can be seen below

Currently Project Agora Commerce utilizes the below 3 Content Standards:

Agora Category&Search
Agora Home
Agora Ingrid

Each one of the above content standards has a different content standard id and a set of banner slot ids.

Requesting a Search Term Banner Ad

Search term Banner ads require a simple "context' to be sent to Project Agora Commerce. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.

Search term Banner Ads use a similar context to Product Ads, you will need your contentStandardId and bannerSlotIds.

The placement attribute for Search term Banner ads has the value "banner-categorysearch".

The Search term Banner Ads use the "Agora Category&Search" content standard.

You will receive your contentStandardId and bannerSlotIdsfrom Project Agora Commerce once your content standard is generated.

The bannerSlotIdsprovided in the examples below are not the ones that will be used.

Below are the minimum values needed to generate a search term ad:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
    "catalogId": "$MY_CATALOG_ID",
    "searchTerm": "string",
    "placement": "string",
    "contentStandardId": "string",
    "bannerSlotIds": ["string"],
    "maxNumberOfAds": number,
    "sessionId": "string"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_here" \
-d \
'{
    "catalogId": "$MY_CATALOG_ID",
    "searchTerm": "string",
    "placement": "string",
    "contentStandardId": "string",
    "bannerSlotIds": ["string"],
    "maxNumberOfAds": number,
    "sessionId": "string"
}'

Exemplar Context

Here is an example of a context:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Chocolate",
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Chocolate",
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP/2 200
{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandx chocolate",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "dc5aff9a-e0b1-4bf8-999f-393329b4afae",
            "slotId": "Search_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "retailer.com/linkforwardedurl",
            "altText": "Search banner for brandx chocolate",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

No customer information or cart items are necessary in this simple context. The simple context consists only of search terms and necessary filters.

In order to properly integrate the Search term Banner ad request the searchTerm value shall contain a variable which is used in the search bar of the website's search page and is filled by user input.

This ensures that the ad request is being executed in every case with the value that users enters in the search bar, so that relative ads will show up.

In order to serve a Banner Ad on your website you will have to use as a creative image the imageUrl , and as a landing page the linkUrl as taken from the above ad response. The id also from this response shall be saved for later use for Impression/Click reporting.

The products field is legacy and can be ignored

The text and gtins fields can be ignored in a standard integration

In gtin field of the above responses you will get the pa_id as in the product feed for the product to be displayed.

pa_id= catprefix--SK

Filtered Searches & Multiple Banners

When a user filters their browsing deeper, you are able to serve ads relevant to their filters using productFilters in the context.

It is necessary for the 2 bannerSlotIds to be created under the same content Standard in order to be used in the same ad request. bannerSlotIds created under different content Standards can't be used in the same request.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["taxonomy:RedWine>Shiraz"]
    ],
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner", "Tile_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["taxonomy:RedWine>Shiraz"]
    ],
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner", "Tile_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}'

As your customers filter deeper in their searches, your request will include more product filters

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
       ["taxonomy:RedWine>Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
    ],
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner", "Tile_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
       ["taxonomy:RedWine>Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
    ],
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner", "Tile_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP/2 200
{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandx red wine",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        },
        {
            "id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Tile_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search tile banner for brandy red wine",
            "text": "",
            "gtins": [
                "catpref--2790492P",
                "catpref--6902690P",
                "catpref--8891466P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandx red wine",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        },
        {
            "id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Tile_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search tile banner for brandy red wine",
            "text": "",
            "gtins": [
                "catpref--2790492P",
                "catpref--6902690P",
                "catpref--8891466P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

Requesting Product Ads

To request Product Ads and Banner Ads in the same request, use the maxNumberOfAds field to specify the number of Product Ads requested.

Below is an example requesting 3 Product Ads and 2 Banner Ads

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
       ["taxonomy:RedWine>Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
    ],
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner", "Tile_Banner"],
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
       ["taxonomy:RedWine>Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
    ],
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner", "Tile_Banner"],
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP/2 200
{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
          
    ],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandx red wine",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        },
        {
            "id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Tile_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandy red wine",
            "text": "",
            "gtins": [
                "catpref--2790492P",
                "catpref--6902690P",
                "catpref--8891466P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
          
    ],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandx red wine",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        },
        {
            "id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Tile_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandy red wine",
            "text": "",
            "gtins": [
                "catpref--2790492P",
                "catpref--6902690P",
                "catpref--8891466P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

sessionId is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page

If you are unsure of the strings displayed on this page. Take a look at the Reference page.

Requesting a Category Banner Ad

Category Banner Ads require a simple "context' to be sent to Project Agora Commerce. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.

Category Banner Ads use a similar context to Product Ads, you will need your contentStandardId and bannerSlotIds.

The placement attribute for Category Banner ads has the value "banner-categorysearch".

The Category Banner Ads use the "Agora Category&Search" content standard.

You will receive your contentStandardId and bannerSlotIdsfrom Project Agora Commerce once your content standard is generated.

The bannerSlotIdsprovided in the examples below are not the ones that will be used.

Minimum Viable Context:

Below are the minimum values needed to generate a category ad:

Exemplar Context

Here is an example of a context:

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

No customer information or cart items are necessary in this simple context. The simple context consists only of necessary filters.

The products field is legacy and can be ignored

The text and gtins fields can be ignored in a standard integration

In gtin field of the above responses you will get the pa_id as in the product feed for the product to be displayed.

pa_id= catprefix--SKU

Filtered Browsing & Multiple Banners

When a user filters their browsing deeper, you are able to serve ads relevant to their filters using productFilters in the context.

As your customers filter deeper in their searches, your request will include more product filters

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

Requesting Product Ads

To request Product Ads and Banner Ads in the same request, use the maxNumberOfAds field to specify the number of Product Ads requested.

Below is an example requesting 3 Product Ads and 2 Banner Ads

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

Brand page Request

Kindly note that the process for requesting a Banner ad ad inside a brand/vendor page is exactly the same except from the Product Filtering which changes like this:

where brand_name is the exact name of the brand as indicated in the product feed.

sessionId is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page

If you are unsure of the strings displayed on this page. Take a look at the Reference page.

Requesting a Middle Home Page Banner Ad

Middle Home Page Banner ads require a simple "context' to be sent to Project Agora Commerce. A "context" is a bit of code that defines the conditions under which an ad is shown to a customer.

Middle Home Page Banner Ads use a similar context to Product Ads, you will need your contentStandardId and bannerSlotIds.

The placement attribute for Middle Home Page Banner ads has the value "banner-home".

The Middle Home Page Banner Ads use the "Agora Home" content standard.

You will receive your contentStandardId and bannerSlotIdsfrom Project Agora Commerce once your content standard is generated.

Please note that both contentStandardId and bannerSlotIds are different for the Middle Home Banner Ad format and will be provided by Project Agora Commerce in the beginning of the integration

The bannerSlotIdsprovided in the examples below are not the ones that will be used.

Context:

Below are the values needed to generate a middle home page ad:

Exemplar Context

Here is an example of a context:

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

No customer information or cart items are necessary in this simple context. The simple context consists only of necessary filters.

The product field is legacy and can be ignored

The text and gtins fields can be ignored in a standard integration

In gtin field of the above responses you will get the pa_id as in the product feed for the product to be displayed.

pa_id= catprefix--SKU

Requesting Product Ads

To request Product Ads and Banner Ads in the same request, use the maxNumberOfAds field to specify the number of Product Ads requested.

Below is an example requesting 3 Product Ads and 2 Banner Ads

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

sessionId is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page

If you are unsure of the strings displayed on this page. Take a look at the Reference page.

Requesting a Top Home Banner Ad

Top Home Banner Ads require a simple "context' to be sent to Project Agora Commerce. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.

Top Home Banner Ads use a similar context to Product Ads, you will need your contentStandardId and bannerSlotIds.

The placement attribute for Top Home Page Banner ads has the value "banner-home".

Top Home Banner Ads will be integrated and serve only in the homepage of a website and the position is defined in the Project Agora Commerce Ad Proposal file provided during the beginning of the integration.

The Top Home Page Banner Ads use the "Agora Home" content standard.

You will receive your contentStandardId and bannerSlotIdsfrom Project Agora Commerce once your content standard is generated.

Please note that both contentStandardId and bannerSlotIds are different for the Top Home Banner Ad format and will be provided by Project Agora Commerce in the beginning of the integration

The bannerSlotIdsprovided in the examples below are not the ones that will be used.

Context:

Below are the values needed to generate a Top Home banner ad:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
    "catalogId": "$MY_CATALOG_ID",
    "placement": "string",
    "contentStandardId": "string",
    "bannerSlotIds": ["string"],
    "maxNumberOfAds": number,
    "sessionId": "string"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_here" \
-d \
'{
    "catalogId": "$MY_CATALOG_ID",
    "placement": "string",
    "contentStandardId": "string",
    "bannerSlotIds": ["string"],
    "maxNumberOfAds": number,
    "sessionId": "string"
}'

Exemplar Context

Here is an example of a context:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "placement": "banner-home",
    "contentStandardId": "e768d5c7-8f73-469d-9240-6bbd93523a97",
    "bannerSlotIds": ["TopHome_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "placement": "banner-home",
    "contentStandardId": "e768d5c7-8f73-469d-9240-6bbd93523a97",
    "bannerSlotIds": ["TopHome_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP/2 200
{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "e768d5c7-8f73-469d-9240-6bbd93523a97",
            "slotId": "TopHome_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Home banner for brandx laptop",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "e768d5c7-8f73-469d-9240-6bbd93523a97",
            "slotId": "TopHome_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Home banner for brandx laptop",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

No customer information or cart items are necessary in this simple context. The simple context consists only of necessary filters.

The product field is legacy and can be ignored

The text and gtins fields can be ignored in a standard integration

In gtin field of the above responses you will get the pa_id as in the product feed for the product to be displayed.

pa_id= catprefix--SKU

If you are unsure of the strings displayed on this page. Take a look at the Reference page.

sessionId is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page

Requesting an Ingrid Banner Ad

Ingrid Banner Ads require a simple "context' to be sent to Project Agora Commerce. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.

Ingrid Banner Ads use a similar context to Product Ads, you will need your contentStandardId and bannerSlotIds.

The placement attribute for Ingrid Banner ads has the value "banner-ingrid".

Ingrid Banner Ads will be integrated and serve only in the category/subcategory pages of a website and the position is defined in the Project Agora Commerce Ad Proposal file provided during the beginning of the integration.

The Ingrid Banner Ads use the "Agora Ingrid" content standard.

You will receive your contentStandardId and bannerSlotIdsfrom Project Agora Commerce once your content standard is generated.

Please note that both contentStandardId and bannerSlotIds are different for the Ingrid Banner Ad format and will be provided by Project Agora Commerce in the beginning of the integration.

The bannerSlotIdsprovided in the examples below are not the ones that will be used.

Minimum Viable Context:

Below are the minimum values needed to generate an ingrid banner ad:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
    "catalogId": "$MY_CATALOG_ID",
    "productFilters": [
      ["taxonomy:string"]
    ],
    "placement": "banner-ingrid",
    "contentStandardId": "string",
    "bannerSlotIds": ["string"],
    "maxNumberOfAds": number,
    "sessionId": "string"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_here" \
-d \
'{
    "catalogId": "$MY_CATALOG_ID",
    "productFilters": [
      ["taxonomy:string"]
    ],
    "placement": "banner-ingrid",
    "contentStandardId": "string",
    "bannerSlotIds": ["string"],
    "maxNumberOfAds": number,
    "sessionId": "string"
}'

Exemplar Context

Here is an example of a context:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:laptops"]
    ],
    "placement": "banner-ingrid",
    "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
    "bannerSlotIds": ["Ingrid_Banner"],
    "maxNumberOfAds": 2,
   "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:laptops"]
    ],
    "placement": "banner-ingrid",
    "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
    "bannerSlotIds": ["Ingrid_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP/2 200
{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
            "slotId": "Ingrid_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Category banner for brandx laptop",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
            "slotId": "Ingrid_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Category banner for brandx laptop",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

No customer information or cart items are necessary in this simple context. The simple context consists only of necessary filters.

The products field is legacy and can be ignored

The text and gtins fields can be ignored in a standard integration

In gtin field of the above responses you will get the pa_id as in the product feed for the product to be displayed.

pa_id= catprefix--SKU

Filtered Browsing

When a user filters their browsing deeper, you are able to serve ads relevant to their filters using productFilters in the context.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
        "productFilters": [
       ["taxonomy:computers>Laptops>Windows"]
    ],
    "placement": "banner-ingrid",
    "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
    "bannerSlotIds": ["Ingrid_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
        "productFilters": [
       ["taxonomy:computers>Laptops>Windows"]
    ],
    "placement": "banner-ingrid",
    "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
    "bannerSlotIds": ["Ingrid_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}'

As your customers filter deeper in their searches, your request will include more product filters

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
        "productFilters": [
        ["taxonomy:computers>Laptops>Windows", "delivery:DeliveryOnly", "pricerange:$250-$500"]
    ],
    "placement": "banner-ingrid",
    "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
    "bannerSlotIds": ["Ingrid_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
        "productFilters": [
        ["taxonomy:computers>Laptops>Windows", "delivery:DeliveryOnly", "pricerange:$250-$500"]
    ],
    "placement": "banner-ingrid",
    "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
    "bannerSlotIds": ["Ingrid_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP/2 200
{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
            "slotId": "Ingrid_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Category banner for brandx Laptop",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
            "slotId": "Ingrid_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Category banner for brandx Laptop",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

Requesting Product Ads

To request Product Ads and Banner Ads in the same request, use the maxNumberOfAds field to specify the number of Product Ads requested.

Below is an example requesting 3 Product Ads and 1 Banner Ads

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
        "productFilters": [
        ["taxonomy:computers>Laptops>Windows", "delivery:DeliveryOnly", "pricerange:$250-$500"]
    ],
    "placement": "banner-ingrid",
    "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
    "bannerSlotIds": ["Ingrid_Banner"],
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
        "productFilters": [
        ["taxonomy:computers>Laptops>Windows", "delivery:DeliveryOnly", "pricerange:$250-$500"]
    ],
    "placement": "banner-ingrid",
    "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
    "bannerSlotIds": ["Ingrid_Banner"],
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP/2 200
{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
          
    ],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
            "slotId": "Ingrid_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Category banner for brandx Laptop",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
          
    ],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Ingrid_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandx red wine",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z"
        }
    ],
    "products": []
}

sessionId is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page

If you are unsure of the strings displayed on this page. Take a look at the Reference page.

The Post Checkout Banner Ad Context

What Are Post Checkout Banner Ads?

Post Checkout Banner Ads are an opportunity for retailers to monetize their website experience after a customer has completed their order. As customers are unlikely to remain on the retailer's site or create an additional order, it is heavily advised that this opportunity is opened to third parties to advertise their relevant banners.

The Post Checkout Banner Ads should be implemented in the Thank you page after a user has completed an order.

Post Checkout Banner Ads require a simple "context' to be sent to Project Agora Commerce. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.

Post Checkout Banner Ads use a similar context to Product Ads, you will need your contentStandardId and bannerSlotIds.

The placement attribute for Post Checkout Banner Ads ads has the value "banner-post-checkout".

Post Checkout Banner Ads will be integrated and serve only in the thank you pages of a website and the position is defined in the Project Agora Commerce Ad Proposal file provided during the beginning of the integration.

The Ingrid Banner Ads use the "Agora Post-checkout" content standard.

You will receive your contentStandardId and bannerSlotIdsfrom Project Agora Commerce once your content standard is generated.

Please note that both contentStandardId and bannerSlotIds are different for the Post Checkout Banner Ad format and will be provided by Project Agora Commerce in the beginning of the integration.

The bannerSlotIdsprovided in the examples below are not the ones that will be used.

Minimum Viable Context:

Below are the minimum values needed to generate a post checkout banner ad:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
    "catalogId": "$MY_CATALOG_ID",
    "placement": "banner-post-checkout",
    "contentStandardId": "string",
    "bannerSlotIds": ["string"],
    "maxNumberOfAds": number,
    "sessionId": "string"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_here" \
-d \
'{
    "catalogId": "$MY_CATALOG_ID",
    "placement": "banner-post-checkout",
    "contentStandardId": "string",
    "bannerSlotIds": ["string"],
    "maxNumberOfAds": number,
    "sessionId": "string"
}'

Exemplar Context

Here is an example of a context:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "placement": "banner-post-checkout",
    "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
    "bannerSlotIds": ["Postcheckout_Banner"],
    "maxNumberOfAds": 2,
   "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "placement": "banner-post-checkout",
    "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
    "bannerSlotIds": ["Postcheckout_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP/2 200
{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
            "slotId": "Ingrid_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Category banner for brandx laptop",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "885d0bf3-0c9a-450f-a3c3-706e228cbb05",
            "slotId": "Ingrid_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Category banner for brandx laptop",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

No customer information or cart items are necessary in this simple context. The simple context consists only of necessary filters.

The products field is legacy and can be ignored

The text and gtins fields can be ignored in a standard integration

In gtin field of the above responses you will get the pa_id as in the product feed for the product to be displayed.

pa_id= catprefix--SKU

sessionId is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page

If you are unsure of the strings displayed on this page. Take a look at the Reference page.

Graceful Fallback in the Event That No Ads Are Displayed

How to ensure your website experience is maintained.

Sometimes Project Agora Commerce might not be able to display Banner Ads on your website. You (the retailer) should be prepared for this situation and should ensure that your website does not display a large empty area where the Banner Ad is expected.

A successfully served Banner Ad

In the rare event the above Banner Ad is not served. The retailer should be prepared to have the Banner Ad area hidden if there is no banner.

A Banner Ad not being served, with the empty area effectively hidden

HTTP/2 200 { "ads": [ { "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==", "gtin": "catpref--2899049P", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2019-12-10T01:46:07.516943179Z" }, { "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==", "gtin": "catpref--9891566P", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2019-12-10T01:46:07.516948637Z" }, { "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==", "gtin": "catpref--2902620P", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, ], "banners": [ { "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==", "contentStandardId": "e768d5c7-8f73-469d-9240-6bbd93523a97", "slotId": "MiddleHome_Banner", "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=", "linkUrl": "https://www.retailer.com/linkforwardedurl", "altText": "Home banner for brandx Laptop", "text": "", "gtins": [ "catpref--2899049P", "catpref--9891566P", "catpref--2902620P" ], "expiry": "2019-12-10T01:46:07.518340479Z", "tags": {} }, { "id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==", "contentStandardId": "e768d5c7-8f73-469d-9240-6bbd93523a97", "slotId": "Tile_Banner", "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=", "linkUrl": "https://www.retailer.com/linkforwardedurl", "altText": "Tile banner for brandy Laptop", "text": "", "gtins": [ "catpref--2790492P", "catpref--6902690P", "catpref--8891466P" ], "expiry": "2019-12-10T01:46:07.518340479Z", "tags": {} } ], "products": [] }

{ "ads": [ { "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==", "gtin": "catpref--2899049P", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2019-12-10T01:46:07.516943179Z" }, { "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==", "gtin": "catpref--9891566P", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2019-12-10T01:46:07.516948637Z" }, { "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==", "gtin": "catpref--2902620P", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, ], "banners": [ { "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==", "contentStandardId": "e768d5c7-8f73-469d-9240-6bbd93523a97", "slotId": "MiddleHome_Banner", "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=", "linkUrl": "https://www.retailer.com/linkforwardedurl", "altText": "Search banner for brandx red wine", "text": "", "gtins": [ "catpref--2899049P", "catpref--9891566P", "catpref--2902620P" ], "expiry": "2019-12-10T01:46:07.518340479Z", "tags": {} }, { "id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==", "contentStandardId": "e768d5c7-8f73-469d-9240-6bbd93523a97", "slotId": "Tile_Banner", "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=", "linkUrl": "https://www.retailer.com/linkforwardedurl", "altText": "Search banner for brandy red wine", "text": "", "gtins": [ "catpref--2790492P", "catpref--6902690P", "catpref--8891466P" ], "expiry": "2019-12-10T01:46:07.518340479Z", "tags": {} } ], "products": [] }

HTTP/2 200 { "ads": [ { "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==", "gtin": "catpref--2899049P", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2019-12-10T01:46:07.516943179Z" }, { "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==", "gtin": "catpref--9891566P", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2019-12-10T01:46:07.516948637Z" }, { "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==", "gtin": "catpref--2902620P", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, ], "banners": [ { "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==", "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9", "slotId": "Search_Banner", "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=", "linkUrl": "https://www.retailer.com/linkforwardedurl", "altText": "Category banner for brandx Laptop", "text": "", "gtins": [ "catpref--2899049P", "catpref--9891566P", "catpref--2902620P" ], "expiry": "2019-12-10T01:46:07.518340479Z", "tags": {} }, { "id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==", "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9", "slotId": "Tile_Banner", "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=", "linkUrl": "https://www.retailer.com/linkforwardedurl", "altText": "Category tile banner for brandy Laptop", "text": "", "gtins": [ "catpref--2790492P", "catpref--6902690P", "catpref--8891466P" ], "expiry": "2019-12-10T01:46:07.518340479Z", "tags": {} } ], "products": [] }

{ "ads": [ { "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==", "gtin": "catpref--2899049P", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2019-12-10T01:46:07.516943179Z" }, { "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==", "gtin": "catpref--9891566P", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, "expiry": "2019-12-10T01:46:07.516948637Z" }, { "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==", "gtin": "catpref--2902620P", "discount": { "amount": 0, "minPrice": 0, "maxPerCustomer": 0 }, ], "banners": [ { "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==", "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9", "slotId": "Category_Banner", "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=", "linkUrl": "https://www.retailer.com/linkforwardedurl", "altText": "Search banner for brandx red wine", "text": "", "gtins": [ "catpref--2899049P", "catpref--9891566P", "catpref--2902620P" ], "expiry": "2019-12-10T01:46:07.518340479Z" }, { "id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==", "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9", "slotId": "Tile_Banner", "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=", "linkUrl": "https://www.retailer.com/linkforwardedurl", "altText": "Search banner for brandy red wine", "text": "", "gtins": [ "catpref--2790492P", "catpref--6902690P", "catpref--8891466P" ], "expiry": "2019-12-10T01:46:07.518340479Z" } ], "products": [] }

Project Agora V2

Overview

What is Project Agora Commerce

What Project Agora Commerce Offers

Basic Overview

How Project Agora Commerce Works

API Introduction

Ad Types

Integration Workflow Options

What Ads Can Project Agora Commerce Serve?

Sponsored Product Listing Ads (SPLs)

Discovery Sponsored Product Listing Ads (DSPLs)

Static Banners

Post Checkout Banner Ads (Optional)

Banner X (Responsive Banner) Ads (Optional)

Accessibility

Readability

Responsivity

Integration

API Introduction

Project Agora Commerce Endpoints

Content Type & Payload

Authenticating Requests

Base URLs

Integration Workflow

Integration Summary

Adserving Summary

Workflow

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6

Step 7

Integration Steps

Workflow

Step 1: Retailer Account initialization

Step 2: Sponsored Product Listings Integration

Step 3: Discovery Sponsored Product Listings Integration

Step 4: Orders Reporting:

Step 5: Static Banner integration

Step 6: Ingrid Static Banner integration

Ad Proposal file

Syncing Data

Introduction

Syncing Data Via File Protocols

Protocols

Data Compression and Encryption

File

Rolling_earliest

Rolling_earliest_24_hours

Rolling_latest

Rolling_latest_24_hours

Conclusion

Syncing Catalog & Products

What Is A Catalog?

What Are Products?

For example:

Product Properties

Product Filters Explained

Category Minimum Bid Filter Structure

Providing Image and Product Name

Syncing Catalogs & Product

Syncing Catalog and Products Via File

XML Files

XML tags in XML documents for products

Syncing Order Data

Why Sync Order Data

Order Attribution Options

Attribution Option: sessionId Attribution

sessionId Overview

Syncing Multiple Orders

Sending Order Data to Project Agora Commerce

Multiple orders

Relevant Context Fields

Reporting Clicks and Impressions

Prerequisite

Integrating Endpoint Calls

Reporting Impressions