> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiderx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# External Ad Sources

> Learn how to integrate external ad networks to optimize ad revenue from your placements.

## Who is this guide for?

This guide is for anyone who sets up external ad integrations with a **Retailer** or **Admin** account.

* You want to use external ads when internal ads alone can't fill your placements
* You want to connect external ad networks such as SSPs and ad exchanges
* You want to plan a strategy to maximize placement revenue

***

## Before you begin

<Note>
  The following requirements must be met:

  * Access to the A2 admin console (Ad Source read/write permission)
  * An **account and integration details** for the external ad network (SSP, ad exchange, etc.) must be ready (signed up)
  * An **API key or credentials** issued by the ad network you are integrating
</Note>

***

## What are external ad sources?

An external ad source connects **external ads to show instead when there are no internal A2 ads**.

For example:

* There are no internal campaigns, or their budget has been exhausted
* Internal ads are insufficient at certain times of day
* An external ad offers a higher price

```mermaid theme={null}
flowchart LR
    A[Ad request] --> B{Internal ad?}
    B -->|Yes| C[Show internal ad]
    B -->|No| D[Call external ad source]
    D --> E{External ad?}
    E -->|Yes| F[Show external ad]
    E -->|No| G[Blank or Passback]
```

This lets you **minimize the time your placements sit empty** and **maximize revenue**.

***

## Step 1: Create an external ad source

### Enter basic information

1. In the **External Ad Sources** menu, click **Create New Source**.
2. Enter the following information:

| Field | Description | Example |
| - | - | - |
| **Name** | A name that is easy to tell apart | "Main SSP", "Secondary network" |
| **Type** | Ad network protocol | OpenRTB, VAST, Custom |
| **Endpoint URL** | External ad server address | `https://adx.example.com/bid` |
| **Publisher ID** | ID used to identify the publisher (optional) | "pub-12345678" |

### Choose an integration type

| Type | Description | When to use |
| - | - | - |
| **OpenRTB** | Real-time bidding protocol | Ad exchanges, most SSPs |
| **VAST** | Video ad standard | Video ad networks |
| **Custom** | Proprietary API integration | Specialized ad networks |

<Tip>
  Most ad networks use the **OpenRTB** type. For networks that only provide video ads, choose **VAST**.
</Tip>

***

## Step 2: Configure authentication

Set up the credentials used to connect to the external ad network.

### Header Parameters

Information to include in the HTTP request headers. Set values such as an API key or an authentication token.

| Key | Example value |
| - | - |
| Authorization | Bearer your-api-key |
| Content-Type | application/json |

### Query Parameters

Parameters to append to the URL. Set values such as the publisher ID or format.

| Key | Example value |
| - | - |
| publisher\_id | pub-12345 |
| format | json |

<Note>
  Credentials are issued by the external ad network. Refer to that network's guide.
</Note>

***

## Step 3: Configure response time

Set how long to wait for a response from the external ad server.

| Setting | Description | Recommended value |
| - | - | - |
| **Timeout** | Response wait time | 100–200ms |

### Timeout guidelines

| Value | Pros | Cons |
| - | - | - |
| **100ms** | Fast page loading | Higher chance of failed responses |
| **200ms** | A good balance | - |
| **300ms+** | Higher response success rate | Slower page loading |

<Warning>
  If the timeout is too long, users may see an empty ad area. We generally recommend **200ms or less**.
</Warning>

***

## Yield optimization strategies

If you have registered multiple external ad sources, you can choose how they are called.

### Waterfall

Calls external ad sources one at a time in a predefined priority order.

```mermaid theme={null}
flowchart TD
    A[Ad request] --> B[Priority 1: SSP A]
    B -->|No response| C[Priority 2: SSP B]
    C -->|No response| D[Priority 3: SSP C]
    B -->|Response| E[Show ad]
    C -->|Response| E
    D -->|Response| E
```

**Pros:** Simple and predictable to set up   **Cons:** Response times can add up

### Header bidding

Sends requests to all external ad sources at once and shows the ad with the highest bid.

```mermaid theme={null}
flowchart TD
    A[Ad request] --> B[Simultaneous requests]
    B --> C[SSP A: ₩1,000]
    B --> D[SSP B: ₩1,200]
    B --> E[SSP C: ₩800]
    C --> F[Select highest bid]
    D --> F
    E --> F
    F --> G[Show SSP B ad]
```

**Pros:** Captures the highest possible revenue **Cons:** More complex to set up and increases server load

<Tip>
  We recommend starting with the **waterfall** approach and switching to **header bidding** as your traffic grows.
</Tip>

***

## Manage external ad sources

### Change priority

When you have multiple sources, you can adjust the order in which they are called.

1. Go to the **External Ad Sources** list.
2. Drag and drop to change the order.
3. Click **Save**.

### Deactivate/delete

You can temporarily pause or delete a specific source.

* **Deactivate**: Keeps the settings but stops calling the source (you can reactivate it later)
* **Delete**: Removes it completely

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="External ads are not being displayed">
    Check the following:

    1. The external ad source is **active**
    2. The endpoint URL is correct
    3. The credentials (API key, etc.) are correct
    4. The timeout is not too short
  </Accordion>

  <Accordion title="Responses take too long">
    Reduce the timeout value, or ask the ad network to improve its response speed. It is a good idea to lower the priority of sources that are consistently slow.
  </Accordion>

  <Accordion title="Is only one of several sources called?">
    With the waterfall approach, if the priority 1 source responds, its ad is shown as is. To select the highest bid across all sources, use header bidding.
  </Accordion>

  <Accordion title="Which takes priority: internal ads or external ads?">
    By default, **internal ads (ads from advertisers the retailer has acquired directly) take priority**. External ad sources are called only when there are no internal campaigns. You can also adjust this order in the yield optimization settings.
  </Accordion>
</AccordionGroup>

***

## Operations checklist

Recommended items to check regularly to run your external ad sources efficiently.

### Daily checks

| Item | Details |
| - | - |
| **Response rate** | Check the response success rate of each source |
| **Fill Rate** | Check the share of impressions filled by external ads |
| **Error logs** | Check for errors such as timeouts and authentication failures |

### Weekly checks

| Item | Details |
| - | - |
| **Revenue by source** | Compare the revenue contributed by each external source |
| **eCPM comparison** | Compare the profitability of internal vs. external ads |
| **Priority review** | Decide whether source priorities need adjusting based on performance |

### Monthly checks

| Item | Details |
| - | - |
| **Integration status** | Check for API key expiration, account status, etc. |
| **New network review** | Explore new ad networks worth adding |
| **Strategy optimization** | Revisit the waterfall vs. header bidding strategy |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.