# Requesting a Home Page Banner Ad

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.

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

{% hint style="info" %}
You will receive your `contentStandardId` and `bannerSlotIds`from Project Agora Commerce once your content standard is generated.

The `bannerSlotIds`provided in the examples below are not the ones that will be used.
{% endhint %}

### Context:

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

{% tabs %}
{% tab title="HTTP" %}

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

{% endtab %}

{% tab title="cURL" %}

```bash
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 \
'{
    "pageType": "Home",
    "catalogId": "$MY_CATALOG_ID",
    "contentStandardId": "string",
    "bannerSlotIds": ["string"],
    "maxNumberOfAds": number
}'
```

{% endtab %}
{% endtabs %}

### Exemplar Context

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

{% tabs %}
{% tab title="HTTP" %}

```yaml
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "pageType": "Home",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Home_Banner"],
    "maxNumberOfAds": 2
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
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 \
'{
    "pageType": "Home",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Home_Banner"],
    "maxNumberOfAds": 2
}'
```

{% endtab %}
{% endtabs %}

### **What Happens when an Ad Is Successfully Requested**

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

{% tabs %}
{% tab title="HTTP" %}

```yaml
HTTP/2 200
{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Home_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": []
}
```

{% endtab %}

{% tab title="cURL" %}

```yaml
{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Home_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": []
}
```

{% endtab %}
{% endtabs %}

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 and Order reporting.

{% hint style="info" %}
The `product` field is legacy and can be ignored

The `text` and `gtins` fields can be ignored in a standard integration
{% endhint %}

{% hint style="info" %}
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--**SKU**
{% endhint %}

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

{% tabs %}
{% tab title="HTTP" %}

```yaml
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
  "pageType": "Home",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Home_Banner", "Tile_Banner"],
    "maxNumberOfAds": 3
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
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 \
'{
 "pageType": "Home",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Home_Banner", "Tile_Banner"],
    "maxNumberOfAds": 3
}'
```

{% endtab %}
{% endtabs %}

### **What Happens when an Ad Is Successfully Requested**

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

{% tabs %}
{% tab title="HTTP" %}

```yaml
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": "Home_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": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "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": []
}
```

{% endtab %}

{% tab title="cURL" %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
If you are unsure of the strings displayed on this page. Take a look at the Reference page.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers-commerce.projectagora.com/integration-guides/banner-ad-integration-guide/requesting-a-home-page-banner-ad.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.