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.

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.

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:

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:

Authenticating Requests

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

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.

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.

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.

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

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.

Sponsored Product Listing Ads (SPLs)

Product Ads at the digital point of purchase will always be one of the most powerful tools for driving discoverability and sales of products, Product Listing Ads allow advertiser to elevate their products to the digital top shelf and promote their products to prime position.

Product Ads served by Project Agora Commerce will typically be merged with a retailer's organic listings before being served to the end user of the retailer's site.

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

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.

A context containing productFilters:

Will only return ads for products containing all filters in the relevant array. Like 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.

Workflow

Step 1: Retailer Account initialization

• Retailer sends the product feed in xml format

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

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

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

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

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

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.

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>

XML tags in XML documents for products

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.

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:

Category Banner
Slot ID - CategoryBanner001
2000px Wide
300px High
Acceptable File Formats: SVG, PNG, JPG

Product Tile Banner Ad:

Product Tile Banner
Slot ID - ProductTileBanner001
200px Wide
375px High
Acceptable File Formats: SVG, PNG, JPG

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.

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.

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.

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.

Field Descriptions

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

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:

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.

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:

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.

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_'."

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:

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.

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:

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.

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

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 https://tools.ietf.org/html/rfc4880. 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

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 descending 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_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.

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:

1. Provide necessary data to Project Agora Commerce to generate your content standard

2. Your content standard will be sent for approval

3. Once approved, your content standard will be loaded into your namespace and your content standard ID will be generated

4. 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.

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.

Context:

Below are the values needed to generate a Top Home banner 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",
    "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.

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.

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:

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.

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.

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:

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:

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:

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:

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"

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

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:

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.

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.

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.

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

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.

What Happens when an Ad Is Successfully Requested

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

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.

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

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

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

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:

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": [
      ["placement:Discovery-Home"]
    ],
    "placement": "discoveryproducts",
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}

-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": [
      ["placement:Discovery-Home"]
    ],
    "placement": "discoveryproducts",
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}'

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"
        }
    ],
    "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"
        },

    ],
    "banners": [],
    "products": []
}

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:

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:Discovery-Category"]
    ],
    "placement": "discoveryproducts",
    "maxNumberOfAds": number,
    "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_here" \
-d \
'{
    "catalogId": "$MY_CATALOG_ID",
    "productFilters": [
      ["taxonomy:string","placement:Discovery-Category"]
    ],
    "placement": "discoveryproducts",
    "maxNumberOfAds": number,
    "sessionId": "23dn3923-323d"
}'

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:

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:Woman","placement:Discovery-Category"]
    ],
    "placement": "discoveryproducts",
    "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:Woman","placement:Discovery-Category"]
    ],
    "placement": "discoveryproducts",
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}'

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": []
}

2nd Ad request

The second ad request should be executed like below:

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": [
      ["placement:Discovery-Category"]
    ],
    "placement": "discoveryproducts",
    "maxNumberOfAds": number,
    "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_here" \
-d \
'{
    "catalogId": "$MY_CATALOG_ID",
      "productFilters": [
      ["placement:Discovery-Category"]
    ],
    "placement": "discoveryproducts",
    "maxNumberOfAds": number,
    "sessionId": "23dn3923-323d"
}'

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:

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:

utm_source=pacommerce&utm_medium=dspl

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.

Minimum Viable Context:

Below are the minimum values needed to generate a post checkout banner 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.

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.