开发者中心

简体中文

English

简体中文

English

Carty 应用内竞价 (In-App Bidding) 集成指南

一、概述 ​

Carty 支持针对移动应用的高性能 应用内竞价 (In-App Bidding)。我们的竞价架构支持移动客户端与 Carty 服务器之间的无缝对接，确保每一次展示机会都能进行实时竞价。

本指南将概述竞价逻辑的核心概念，并详细说明如何通过 Carty SDK 集成 Header Bidding（头部竞价）。通过参与统一竞价拍卖（Unified Auction），开发者可以比传统瀑布流（Waterfall）模式获得更高的收益（Yield），并显著降低广告加载延迟。

支持的广告格式 Carty SDK 支持以下 5 种主流广告格式的 Header Bidding 接入，确保全场景的变现覆盖：

  • 横幅广告 (Banner): 标准及自适应展示广告。
  • 原生广告 (Native): 高度自定义的资产组合, 融入应用 UI。
  • 插屏广告 (Interstitial): 全屏静态图或视频广告。
  • 激励视频 (Rewarded Video): 高参与度的用户主动激励视频。
  • 开屏广告 (App Open): 应用热启动或冷启动时展示的高价值广告。

二、集成介绍 ​

  • 在广告曝光机会到来之前，In-house Client 需先调用 Carty SDK 获取 buyerUid，并将该 buyerUid 传递至 In-house Server。
  • 随后，In-house Server 将以并发方式向 Carty Server 发起 OpenRTB 请求。当收到来自 Carty 的广告出价响应后，需在 In-house Auction System 中完成比价，并将最终结果（adm）返回给 In-house Client。
  • 接下来，In-house Client 需调用 Carty SDK 的广告加载接口，并传入返回的 adm 以完成广告加载与展示。同时，集成方需正确处理 Win/Loss/Billing 通知，以确保竞价结果和计费流程的准确性。

Header Bidding Architecture

SDK集成接入说明 ​

在集成应用头部竞价逻辑之前，请先确保你已经阅读过Carty SDK的Android集成文档（或者iOS集成文档）或者已集成Carty SDK到你的项目中。

三、 Android 集成说明 ​

3.1 初始化SDK

建议在Application onCreate方法中调用SDK初始化方法。SDK初始化方法无耗时操作，无特殊使用场景，建议在主线程调用。

java
CTAdConfig adConfig = new CTAdConfig.Builder()
        .setAppId("YOUR_APP_ID")// 开发者后台申请的appId
        .setChannel("YOUR_APP_CHANNEL")// 媒体channel
        .setDebug(BuildConfig.DEBUG)// debug模式  传true会有测试日志打印
        .build();
CTAdSdk.init(applicationContext, adConfig, new CTAdSdk.CTInitListener() {
    @Override
    public void onInitSuccess() {
    }
    
    @Override
    public void onInitFailed(CTAdError adError) {
    }
});

3.2 获取buyerUID

通过静态方法**CTAdSdk.getBuyerUid()** 来获取buyerUID，并将这个buyerUID告知你自己的服务端，用于执行服务端的竞价请求，建议您在每次竞价请求前重新获取buyerUID。

3.3 加载服务端竞价后返回的广告

构建 CTAdRequest 时，传入 admString 。

java
CTAdRequest adRequest = new CTAdRequest.Builder()
    .setPlacementId("SPLASH_PLACEMENT_ID")
    .setAdmString("ADM_STRING")
    .build();
CTSplash ctSplash = new CTSplash(adRequest);
ctSplash.loadAd();

四、iOS 集成说明 ​

4.1 初始化SDK

在AppDelegate里的如下方法中调用SDK的初始化方法。初始化时，SDK会从服务器拉取配置信息。建议在主线程调用此方法。

- (void)start:(NSString *)appid completion:(void (^)(void))completion;

示例：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{
    [[CTExchange sharedInstance] start:@"abc123" completion:^{

    }];
}

4.2 获取buyerUID

通过调用静态方法**[CTExchange bidderToken]** 来获取用户标识buyerUID，并将这个buyerUID告知你自己的服务端，用于执行服务端的竞价请求Object：User，建议您在每次初始化应用后或每次竞价前重新获取

4.3 加载竞价后返回的adm数据

通过各loadWithAdmStringAPI加载广告。

示例：

[interstitialAd loadWithAdmString:@"[ADM_STRING]"];

五、服务端 OpenRTB 竞价集成指南 ​

如果开发者希望通过服务端（S2S）模式直接与 Carty 服务器进行竞价，所有请求必须遵循 OpenRTB 2.6 协议规范。

5.1 竞价请求 (Bid Request)

请求地址 (Endpoint)：https://ssp.carty.com/openrtb2/auction

请求头 (Headers):

  • Content-Type: application/json
  • x-openrtb-version: 2.6
  • Content-Encoding: gzip (强烈建议开启，以降低网络延迟)

请求内容（关键字段）：

字段属性类型描述
idstring请求唯一标识: 由竞价平台/交易平台生成，用于标识单次交易。
imp.tagidstringCarty 广告位 ID: 对应 Carty 开发者后台生成的 Placement ID。
imp.bidfloorfloat底价: 该次展示的最低 CPM 价格。
imp.bidfloorcurfloat币种: 底价对应的货币代码 (ISO 4217)，默认为 USD。
device.ip /
device.ipv6		stringIP 地址: 终端用户设备的公网 IPv4 或 IPv6 地址。
user.buyeruidstringCarty 买家 ID: 由 Carty SDK 生成的唯一用户标识，用于用户匹配，此字段为必填。
testinteger测试模式: 0 为正式流量；1 为测试/沙盒模式。
tmaxinteger超时时间: 等待竞价响应的最大时长（毫秒），含网络延迟。建议设置为 2000。

5.2 竞价响应 (Bid Response) 当 Carty 参与竞价时，将返回 HTTP 200 OK 响应。实际的广告素材（Markup）包含在 seatbid.bid.adm 字段中。

HTTP 状态码：

  • 200 OK: 成功返回竞价。
  • 204 No Content: 无广告填充（静默丢弃）。

响应内容（关键字段）：

字段属性类型描述
seatbid.bid.nurlstring赢价通知 URL: 竞价胜出时调用。需将 ${AUCTION_MIN_TO_WIN} 宏替换为最终成交价。
seatbid.bid.lurlstring竞败通知 URL: 竞价失败时调用。支持 ${AUCTION_PRICE}（出价宏）和 ${AUCTION_LOSS}（竞败原因宏）。
seatbid.bid.burlstring计费通知 URL: 当广告成功展示并触发计费时调用。
seatbid.bid.admstring广告内容 (Markup): 原始广告字符串。必须将此值原样传递给 Carty SDK 的相关接口进行渲染。

5.3 开发者实现要点

  • 宏替换: 请确保您的服务器逻辑在触发 nurl 或 lurl 之前，已正确解析并替换 OpenRTB 宏（如 ${AUCTION_PRICE}）。
  • SDK 接入: 无论通过何种平台进行 Header Bidding，服务端获取的 adm 字符串必须完整透传至客户端 SDK，以确保广告渲染和转化归因的准确性。
  • 超时管理: 为了最大化填充率，请确保您的服务端 tmax 设置与聚合平台的竞价超时设置保持一致。

5.4 集成示例与对象说明 为了确保集成成功，开发者应密切关注每种广告格式的具体对象要求。以下提供了 横幅广告 (Banner)、视频广告 (Video) 和 原生广告 (Native) 的详细 JSON 示例及说明。

5.4.1 横幅广告 (Banner Ad - 标准展示类)

横幅广告请求最为常见，通常需要固定的尺寸规格。banner 对象必须包含应用界面支持的尺寸（例如：智能手机常用的 320x50 或平板电脑常用的 728x90）。

5.4.1 竞价请求示例：

json
{
  "id": "req_banner_001",
  "imp": [{
    "id": "1",
    "tagid": "carty_placement_banner_123",
    "bidfloor": 0.50,
    "bidfloorcur": "USD",
    "banner": {
      "w": 320,
      "h": 50,
      "pos": 1,
      "api": [3, 5],
      "mimes": ["text/html", "image/jpeg", "image/png"]
    }
  }],
  "device": { "ip": "192.168.1.1", "ua": "Mozilla/5.0..." },
  "user": { "buyeruid": "carty_user_token_abc" }
}

5.4.1.2 竞价响应示例：

json
{
  "id": "req_banner_001",
  "seatbid": [{
    "bid": [{
      "price": 0.75,
      "adm": "{\"type\":\"html\",\"content\":\"<html>...</html>\"}",
      "nurl": "https://ssp.carty.io/win?p=${AUCTION_MIN_TO_WIN}"
    }]
  }]
}

5.4.2. 视频广告 (Video Ad - 插屏或激励视频) 视频请求遵循 VAST (Video Ad Serving Template) 协议。由于需要定义视频的技术规格以确保与设备的播放器兼容，这类请求相对复杂。

5.4.2.1 竞价请求示例：

json
{
  "id": "req_video_002",
  "imp": [{
    "id": "1",
    "tagid": "carty_placement_video_456",
    "video": {
      "mimes": ["video/mp4", "video/webm"],
      "minduration": 5,
      "maxduration": 30,
      "protocols": [2, 3, 5, 6],
      "w": 320,
      "h": 480,
      "linearity": 1,
      "delivery": [1],
      "ext": { "rewarded": 1 }
    }
  }],
  "device": { "ip": "192.168.1.1", "ua": "Mozilla/5.0..." },
  "user": { "buyeruid": "carty_user_token_abc" }
}

5.4.2.2 竞价响应示例：

json
{
  "id": "req_video_002",
  "seatbid": [{
    "bid": [{
      "price": 12.50,
      "adm": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><VAST>...</VAST>",
      "nurl": "https://ssp.carty.io/win?p=${AUCTION_MIN_TO_WIN}"
    }]
  }]
}

5.4.3. 原生广告 (Native Ad - 结构化内容) 原生广告提供了最高级别的自定义自由度。请求中不会直接返回渲染好的图像或 HTML，而是指定一系列 资产 (Assets)（如标题、图标、主图、描述），应用将利用这些数据构建自定义的 UI 界面。

5.4.3.1 竞价请求示例：

json
{
  "id": "req_native_003",
  "imp": [{
    "id": "1",
    "tagid": "carty_placement_native_789",
    "native": {
      "request": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":80}},{\"id\":2,\"required\":1,\"img\":{\"type\":3,\"wmin\":1200,\"hmin\":627}},{\"id\":3,\"required\":0,\"data\":{\"type\":12,\"len\":15}}]}}",
      "ver": "1.2"
    }
  }],
  "device": { "ip": "192.168.1.1", "ua": "Mozilla/5.0..." },
  "user": { "buyeruid": "carty_user_token_abc" }
}

5.4.3.2 竞价响应示例：

json
{
  "id": "req_native_003",
  "seatbid": [{
    "bid": [{
      "price": 3.20,
      "adm": "{\"native\":{\"assets\":[{\"title\":{\"text\":\"Sample\"}},...]}}",
      "nurl": "https://ssp.carty.io/win?p=${AUCTION_MIN_TO_WIN}"
    }]
  }]
}