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:

"productFilters": [   "taxonomy:RedWine>Shiraz",    "type:Australian",    "delivery:DeliveryOnly",    "price-range:$25-$50"   ],

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

[   "taxonomy:RedWine>Shiraz",    "type:Australian",    "delivery:DeliveryOnly",    "price-range:$25-$50"],

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

"productFilters": ["taxonomy:RedWine"]

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:

"imageurl:https://your.image.host.com/image.jpg","name:product name"

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.