> For the complete documentation index, see [llms.txt](https://docs.targetpick.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.targetpick.io/targetpick_eng/for-ssp/banner.md).

# Banner

## **1. REQUEST**

Construct the content below in JSON format according to the OpenRTB 2.5 specification, then call the above URL using the POST method.

Currently, only the information for fixed-price transactions is defined in the [OpenRTB 2.5 ](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf)specification. Information for RTB (Real-Time Bidding) will be added in a future update.

### **Request object**

| Field     | Type         | Required | Description                                                                     |
| --------- | ------------ | -------- | ------------------------------------------------------------------------------- |
| ssp\_id   | string       | Y        | SSP ID (issued by TARGETPICK)                                                   |
| id        | string       | Y        | Unique request ID                                                               |
| cur       | string array | N        | Currency for auction (ISO-4217-alpha), e.g., “KRW”                              |
| imp       | object array | Y        | Refer to the [`imp`](#imp) object                                               |
| site      | object       | Y        | Refer to the [`site`](#site) object                                             |
| app       | object       | Y        | Refer to the [`app`](#app) object                                               |
| publisher | object       | Y        | Refer to the [`publisher`](#publisher) object                                   |
| device    | object       | Y        | Refer to the [`device`](#device) object                                         |
| user      | object       | Y        | Refer to the [`user`](#user) object                                             |
| at        | integer      | Y        | <ul><li>0: fixed price</li><li>1: first price</li><li>2: second price</li></ul> |
| tmax      | integer      | Y        | Maximum timeout (ms)                                                            |
| bcat      | string array | N        | Block advertiser categories based on IAB categories                             |
| badv      | string array | N        | Block advertiser domains                                                        |
| bapp      | string array | N        | Block app bundle or package names                                               |

### **Imp**

| Field             | Type    | Required | Description                                                                                                                        |
| ----------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| id                | string  | Y        | Unique impression ID                                                                                                               |
| bidfloor          | float   | Y        | Minimum bid price (e.g., 4.12)                                                                                                     |
| bidfloorcur       | string  | Y        | Currency (e.g., KRW)                                                                                                               |
| secure            | integer | Y        | <ul><li>0: http</li><li>1: https</li></ul>                                                                                         |
| banner            | object  | Y        | Refer to the [`banner`](#banner) object                                                                                            |
| instl             | integer | Y        | <p>Indicates interstitial  (default : 0)</p><ul><li>1: the ad is interstitial or full screen</li><li>0: not interstitial</li></ul> |
| displaymanager    | string  | Y        | SSP platform or SDK name                                                                                                           |
| displaymanagerver | string  | Y        | SSP platform or SDK version                                                                                                        |

### **Banner**

> [imp](https://docs.meba.kr/s-plus/api/dsp/delivery/banner/#banner_imp) / banner

| Field | Type    | Required | Description   |
| ----- | ------- | -------- | ------------- |
| w     | integer | Y        | Banner width  |
| h     | integer | Y        | Banner height |

### **Site**

| Field  | Type         | Required | Description                   |
| ------ | ------------ | -------- | ----------------------------- |
| id     | string       | Y        | Unique site ID managed by SSP |
| name   | string       | N        | Site name                     |
| domain | string       | Y        | Site domain                   |
| page   | string       | N        | Page URL                      |
| ref    | string       | N        | Referrer URL                  |
| cat    | string array | N        | Categories                    |

### **App**

| Field    | Type         | Required | Description                  |
| -------- | ------------ | -------- | ---------------------------- |
| id       | string       | Y        | Unique app ID managed by SSP |
| name     | string       | N        | Application name             |
| bundle   | string       | Y        | Bundle or package name       |
| storeurl | string       | N        | App store URL                |
| cat      | string array | N        | Categories                   |

### **Publisher**

| Field | Type   | Required | Description  |
| ----- | ------ | -------- | ------------ |
| id    | string | Y        | Publisher ID |

### **Device**

| Field | Type   | Required | Description                         |
| ----- | ------ | -------- | ----------------------------------- |
| ua    | string | Y        | User Agent                          |
| ip    | string | Y        | IPv4 address                        |
| model | string | N        | Device model                        |
| os    | string | Y        | iOS , Android, mobile\_web, pc\_web |
| osv   | string | Y        | OS version (e.g., 8.1, 9.2)         |
| ifa   | string | Y        | Apple IFA or Google ADID            |
| geo   | object | N        | Country code (ISO 3166-1 Alpha-3)   |

{% hint style="danger" %}

* User Agent (UA) is <mark style="color:red;">**required**</mark> for ad exchange transactions.
* IP <mark style="color:red;">**must be a public IP**</mark>. Using private IP (e.g., from internal networks or routers) may limit ad delivery.
  {% endhint %}

### **User**

| Field    | Type   | Required | Description                            |
| -------- | ------ | -------- | -------------------------------------- |
| buyeruid | string | Y        | Cookie matching ID received from Mezzo |

### **Example**

{% tabs %}
{% tab title="APP" %}
{% code lineNumbers="true" %}

```json
{
	"id": "req-12345-abcde",
	"imp": [{
		"id": "1",
		"bidfloor": 0,
		"secure": 0,
		"bidfloorcur": "KRW",
		"instl": 0,
		"banner": {
			"w": 320,
			"h": 50,
			"btype": [1, 3, 4]
		}
	}],
	"app": {
		"id": "g0r8k3u5",
		"name": "test",
		"bundle": "com.test",
		"storeurl": "http://test.com",
	    "publisher": {
		    "id": "publisher_id"
	    },
		"cat": ["IAB3"]
	},
	"device": {
		"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 6_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9A334 Safari/7534.48.3",
		"ip": "123.123.123.123",
		"ifa": "2B2D9FE6-F84F-4A36-86AA-5C3769DD1082",
		"os": "iOS",
		"osv": "8.1",
		"model": "iPhone6",
		"geo":{"country":"KOR"}
	},
	"user": {
      "buyeruid": "923123"
   }
}
```

{% endcode %}
{% endtab %}

{% tab title="WEB" %}
{% code lineNumbers="true" %}

```json
{
	"id": "req-12345-abcde",
	"imp": [{
		"id": "1",
		"bidfloor": 0,
		"secure": 0,
		"bidfloorcur": "KRW",
		"instl": 0,
		"banner": {
			"w": 320,
			"h": 50,
			"btype": [1, 3, 4]
		}
	}],
	"site": {
		"id": "g0r8k3u5",
		"name": "test",
		"domain": "gamefocus.co.kr",
		"page": "http://gamefocus.co.kr",
		"ref": "http://www.naver.com",
		"publisher": {
		    "id": "publisher_id"
	    },
		"cat": ["IAB3"]
	},
	"device": {
		"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 6_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9A334 Safari/7534.48.3",
		"ip": "123.123.123.123",
		"ifa": "2B2D9FE6-F84F-4A36-86AA-5C3769DD1082",
		"os": "iOS",
		"osv": "8.1",
		"model": "iPhone6",
		"geo":{"country":"KOR"}
	},
	"user": {
      "buyeruid": "923123"
   }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

##

## **2. RESPONSE**

Respond by composing the ad information in JSON format according to the OpenRTB 2.5 specification.

Currently, only information for fixed-price transactions is included, and RTB (Real-Time Bidding) details will be added later.

| Filed    | Type         | Required | Description                          |
| -------- | ------------ | -------- | ------------------------------------ |
| id       | string       | Y        | Bid Request ID                       |
| bidid    | string       | Y        | Bid response ID                      |
| cur      | string       | N        | Bid currency in ISO-4217 code        |
| seatbid  | object array | Y        | Seat Bid object                      |
| seat     | string       | Y        | Bidder qualification code (not used) |
| bid      | object array | Y        | Array of Bid objects                 |
| id       | string       | Y        | Bid object ID                        |
| impid    | string       | Y        | Impression object ID                 |
| price    | float        | N        | Bid price                            |
| adm      | string       | Y        | Ad markup                            |
| iurl     | string       | Y        | Image URL                            |
| nurl     | string       | Y        | Impression URL                       |
| clickurl | string       | Y        | Click URL                            |

### Macro Applied on Tracking URL Call <a href="#macro-applied-on-tracking-url-call" id="macro-applied-on-tracking-url-call"></a>

{% hint style="info" %}
In the response, if the values of the nurl, clickurl, or adm fields contain the macros below, replace them before responding.
{% endhint %}

<table><thead><tr><th width="200">Macro</th><th>Description</th></tr></thead><tbody><tr><td>${AUCTION_ID}</td><td>Replaced with the Bid Request ID so the tracking URL is called from the SSP</td></tr><tr><td>${AUCTION_PRICE}</td><td>Replaced with the WIN price on the SSP side. Converted to an encrypted integer value of 0 or greater. <br>(The encryption method will be provided later.)</td></tr><tr><td>${SSP_CLICK_URL}</td><td>URI-encoded and replaced with a URL that allows the SSP to verify the click event by calling the SSP URL when a click event occurs</td></tr><tr><td>${SSP_CLICK_URL:2}</td><td>URI-encoded twice and replaced macro. When a click event occurs, the SSP URL is called so the click event can be verified</td></tr></tbody></table>

### **Example**

{% tabs %}
{% tab title="Response" %}
{% code lineNumbers="true" %}

```json
{
	"id": "req-12345-abcde",
	"bidid": "mezzomedia",
	"cur": "KRW",
	"seatbid": [{
		"seat": "512",
		"bid": [{
			"id": "147704390800",
			"impid": "1",
			"price": "40",
			"adm": "<html><head><meta name='viewport' content='width=device-width; height=device-height;'><title></title></head><body style='margin:0px;'><style type='text/css'> #mz_first {position:absolute; left:0; top:0};</style><link href='http://abc.com/ad_images/r_main.css' rel='stylesheet' type='text/css' /><div id='mz_wrap' style='text-align:center;background-color:#000000; margin:0 auto; padding:0; text-decoration: none; width:100%;'><article id='mz_article' style='height:50px; margin:0 auto; overflow:hidden; position:relative; width:320px;'><a href='http://abc.com/ad_tracking.mezzo/?e_request_type=click&e_cp=${AUCTION_PRICE}&' target='_blank'><img id='mz_first' src='http://advimg.ad-mapps.com/ad_images/20160329_crewbi_2w_320x50.png' width='320' height='50'></a><div id='mz_beacon' style='position:absolute; left:0px; top:0px; visibility:hidden;'><img src='http://abc.com/ad_tracking.mezzo/?e_request_type=imps_tracking&e_cp=${AUCTION_PRICE}&'></div></article></div></body></html>",
			"w": "320",
			"h": "50",
			"iurl": "http://abc.com/ad_images/20160329_abc_320x50.png",
			"nurl": "http://abc.com/ad_tracking.mezzo/?e_request_type=imps_tracking&e_cp=${AUCTION_PRICE}&",
			"ext": {
				"clickurl": "http://abc.com/ad_tracking.mezzo/?e_request_type=click&e_cp=${AUCTION_PRICE}&"
			}
		}]
	}]
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## &#x20;<a href="#cookie-matching" id="cookie-matching"></a>

## 3. Cookie Matching <a href="#cookie-matching" id="cookie-matching"></a>

{% hint style="warning" %}
The web performs ad audience matching through a separate process.
{% endhint %}

<table data-header-hidden><thead><tr><th width="85"></th><th></th></tr></thead><tbody><tr><td>1</td><td><p>SSP provides a URL for cookie matching to the DSP: </p><p><code>http://ssphost/match?dsp_user_id={dsp_uid}</code></p></td></tr><tr><td>2</td><td>DSP installs the above URL in advance as a beacon on advertiser or service pages where cookie matching is possible. (At least 2–3 weeks before integration.)</td></tr><tr><td>3</td><td>When an audience visits the installed page, the browser requests the SSP URL with dsp_uid, and the SSP issues a cookie for the received dsp_uid value to ssphost.</td></tr><tr><td>4</td><td>Going forward, the SSP includes the issued dsp_uid value in Bid Requests sent to the DSP.</td></tr></tbody></table>

### Ad Server Error Codes <a href="#a-d-server-error-codes" id="a-d-server-error-codes"></a>

<table><thead><tr><th width="85">Code</th><th>Description</th></tr></thead><tbody><tr><td>3</td><td>Invalid parameter information delivered (invalid bid request)</td></tr><tr><td>4</td><td>No TARGETPICK inventory (invalid bid request)</td></tr><tr><td>5</td><td>No ad creative to serve</td></tr><tr><td>98</td><td>Invalid tracking information</td></tr><tr><td>99</td><td>Ad server error</td></tr></tbody></table>

### HTTP Response Status Codes <a href="#http-response-status-codes" id="http-response-status-codes"></a>

| Status Code | Description              | Body           |
| ----------- | ------------------------ | -------------- |
| 200         | Successful bid           | Refer to 2.3.2 |
| 204         | No bid / give up bidding | Empty body     |
| 400         | Invalid bid request      | Refer to 2.3.3 |

## &#x20;<a href="#skadnetwork-support-ios-14" id="skadnetwork-support-ios-14"></a>

## 4. SKAdNetwork Support (iOS 14+) <a href="#skadnetwork-support-ios-14" id="skadnetwork-support-ios-14"></a>

{% hint style="info" %}
**This section describes support for campaigns where SKAdNetwork is enabled on iOS 14 or later.**
{% endhint %}

<table data-header-hidden><thead><tr><th width="85"></th><th></th></tr></thead><tbody><tr><td>1</td><td>The DSP must be registered as an Ad Network in Apple’s SKAdNetwork API.<br>(https://developer.apple.com/documentation/storekit/skadnetwork/registering_an_ad_network)</td></tr><tr><td>2</td><td>A public key must be issued by Apple and a postback URL must be configured.</td></tr><tr><td>3</td><td>The SKAdNetwork ID issued by Apple must be shared with CJ MezzoMedia, which will request registration in the publisher’s info.plist.</td></tr><tr><td>4</td><td>When returning a response for SKAdNetwork-enabled campaigns, the DSP must include the SKAdNetwork ID and all related fields.</td></tr><tr><td>5</td><td>The advertiser app must register via registerAppForAdNetworkAttribution().</td></tr><tr><td>6</td><td>The DSP can receive install data via SKAdNetwork.</td></tr></tbody></table>

### Additional Fields in Ad Request (SKAdNetwork) <a href="#additional-fields-in-a-d-request-skadnetwork" id="additional-fields-in-a-d-request-skadnetwork"></a>

> BidRequest / imp / banner / ext / skadn

Prerequisites:

<table data-header-hidden><thead><tr><th width="85">1</th><th>DSP에서 제공하는 SKAdNetwork ID가 퍼블리셔의 info.plist에 등록되어 있어야 한다.</th></tr></thead><tbody><tr><td>1</td><td>The DSP’s SKAdNetwork ID must be registered in the publisher’s info.plist.</td></tr><tr><td>2</td><td>The user device must run iOS 14 or higher.</td></tr><tr><td>3</td><td>A version of the SDK that supports SKAdNetwork must be installed.</td></tr><tr><td>4</td><td>The DSP must comply with CJ MezzoMedia Bid Request specifications.</td></tr></tbody></table>

| Field      | Type   | Required | Description                                                                   | Example                                  |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ---------------------------------------- |
| version    | string | Y        | SKAdNetwork version (2.0 or higher)                                           | “version”:”2.0”                          |
| sourceapp  | string | Y        | Publisher app ID registered in Apple App Store. Matches BidRequest.app.bundle | “sourceapp”:”000000000”                  |
| skadnetids | string | Y        | SKAdNetwork IDs registered in publisher’s info.plist                          | “skadnetids”:\[“feyaarzu9v.skadnetwork”] |

### Additional Fields in Ad Response **(SKAdNetwork)**

> BidResponse / imp / banner / ext / skadn

| Field      | Type   | Required | Description                                                             | Example                                         |
| ---------- | ------ | -------- | ----------------------------------------------------------------------- | ----------------------------------------------- |
| version    | string | Y        | SKAdNetwork version (2.0 or higher)                                     | “version”:”2.0”                                 |
| network    | string | Y        | Ad network identifier. Must match at least one skadnetid in the request | “network”:\[“feyaarzu9v.skadnetwork”]           |
| campaign   | string | Y        | Campaign ID (integer between 1 and 100 per Apple spec)                  | “campaign”:”45”                                 |
| itunesitem | string | Y        | Advertiser app ID in App Store. Matches BidResponse.bid.bundle          | “itunesitem”:”123456789”                        |
| nonce      | string | Y        | Unique ID for each ad response                                          | “nonce”:”123b1a78-b5ef-98ad-1234-ab-c4effa00b8” |
| sourceapp  | string | Y        | Publisher app ID. Matches BidRequest.imp.ext.skad.sourceapp             | “sourceapp”:”000000000”                         |
| timestamp  | string | Y        | Unix time as a string                                                   | “timestamp”:”1234567890”                        |
| signature  | string | Y        | SKAdNetwork signature provided by Apple                                 | “signature”:”ABCDEFGHijkl-lmb…”                 |

### **Example**

{% tabs %}
{% tab title="Request" %}
{% code lineNumbers="true" %}

```json
{
	"imp":[{
        "ext": {
          "skadn": {
            "version": "2.0",
			"sourceapp": "000000000",
			"skadnetids": ["feyaarzu9v.skadnetwork", "8sRFag4vVC.skadnetwork"]
			}
			}
		}]
}
```

{% endcode %}
{% endtab %}

{% tab title="Response" %}
{% code lineNumbers="true" %}

```json
{
	"seatbid": [{
		"bid": [{
			"ext": {
				"skadn": {
					"version": "2.0",
					"network": "feyaarzu9v.skadnetwork ",
					"campaign": "45",
					"itunesitem": "123456789",
					"nonce": "123b1a78-b5ef-98ad-1234-ab-c4effa00b8",
					"sourceapp": "000000000",
					"timestamp": "1234567890",
					"signature": "ABCDEFGHijkl-lmbKBSE8QnhLTIHZZZWCFgZpRqRxHss65KoFAiAJgJKjdrWdkLUOCCjuEx2RmFS7daRzSVZRVZ8RyMyUXg"
				}
			}
		}]
	}]
}
```

{% endcode %}
{% endtab %}
{% endtabs %}