HTTP API 源 | Docs

概述

TTO CDP HTTP API 是一個開放式數據收集接口，允許外部系統通過 HTTP 協議將用戶行為數據和用戶畫像數據發送到TTO客戶數據平台（TTO CDP）。該 API 遵循標準的 Event Tracking 規範，支持用戶識別、事件追蹤、用戶別名管理等核心功能。

入門

獲取 API 密鑰

訪問您的 TTO CDP 後臺，進入 My Sources ，加號選擇添加源。

選擇 HTTP API源。

填寫基本信息，保存。創建成功后后，系統会自動生成生成唯一的 API 密鑰。

注意：儅通過API向 TTO CDP 發送數據時，請求體中必須添加 API 密鑰字段，具體信息在請見以下文檔

數據收集接口

基礎 URL：https://cdp.cs.topkee.com

路徑	請求方法	用途
/v1/track	POST	用於追蹤用戶在網站或應用中的具體行為事件。
/v1/identify	POST	識別用戶身份並更新用戶畫像信息。
/v1/alias	POST	合併不同用戶身份，解決用戶多設備、多身份問題。
/v1/settings	POST	獲取數據源配置信息。

使用API推送數據

API 概述

共有字段説明

字段名	説明
type	事件類型，標識操作類型（track/identify/alias）
api_key	項目API密鑰，用於身份驗證和數據歸屬
msg_id	消息唯一標識符，用於去重和日志追鐘
user_id	外部平臺用戶ID，用於去重和日志追蹤
anonymous_id	匿名ID，存儲在訪問者瀏覽器中，有效期爲2年
timestamp	事件發生時間戳（秒）
context	上下文信息，包含設備、頁面、流量來源等元數據

數據字段

traits：可選，請參考標準字段填寫信息

{
    "email": "Email address",
    "phone": "Phone number (with area code, e.g. US phone (650)555-1212 should be 16505551212)",
    "first_name": "First name (lowercase a-z, no punctuation, e.g. Mary becomes mary)",
    "last_name": "Last name (lowercase a-z, no punctuation)",
    "date_date": "Birth date (YYYYMMDD, e.g. 19970216)",
    "gender": "Gender (f for female, m for male)",
    "city": "City (lowercase letters only, no punctuation, special characters or spaces: newyork, london)",
    "state": "State/Province (please enter 2-character ANSI abbreviation code in lowercase: az, ca)",
    "zip_post": "ZIP code (no spaces or hyphens)",
    "country": "Country (lowercase letters: hk, us)",
    "ip": "Valid IP address",
    "avatar": "Avatar",
    "name": "Full name",
    "username": "Username",
    "title": "Job title",
    "description": "Description",
    "company": "Company",
    "website": "Website",
    "address": "Address",
    "id": "External data primary key ID",
    "age": "Age",
    "created_at": "User creation time"
}

properties：可選，備註：收入|貨幣|值爲標準事件屬性，其他鍵爲自定義

{
	"currency": "HKD", 
	"value": 20.24, 
	"key1": "diy 1"
}

products：用於電子商務網站場景

[{
  "id": "Product ID",
  "name": "Product name",
  "price": "Product price",
  "currency": "Currency",
  "affiliation": "Product associated store",
  "coupon": "Coupon",
  "discount": "Discount",
  "index": "Product index position in list",
  "category": "Product category",
  "category2": "Product secondary category",
  "category3": "Product tertiary category",
  "category4": "Product quaternary category",
  "category5": "Product quinary category",
  "brand": "Brand",
  "variant": "Variant",
  "quantity": "Quantity",
  "list_id": "List ID",
  "list_name": "List name",
  "location_id": "Location (e.g. physical store)",
}]

推送事件數據 Track

説明

track是 TTO CDP 中最核心的数据收集端点，用于记录用户在网站、应用或服务中的具体行为事件。

接口信息

請求URL：https://cdp.cs.topkee.com/v1/track

請求方法：POST

請求參數

字段	類型	必須	描述
event	STRING	是	事件名稱，如 "Purchase", "PageView" 等。
properties	STRING	是	事件屬性，包含業務相關數據，詳見屬性文檔。
traits	STRING	是	用戶特徵信息，包含郵箱、電話等畫像數據

請求示例

curl -X 'POST' \
  'https://cdp.cs.topkee.com/v1/track' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "track",
  "api_key": "your_api_key_here",
  "msg_id": "unique_message_id_123",
  "user_id": "user_12345",
  "event": "Purchase",
  "properties": {
    "revenue": 299.99,
    "currency": "USD",
    "product_id": "PROD_001"
  },
  "timestamp": "1767174918",
  "traits": {
    "name": "alelos",
    "email": "1234567@123.com",
    "phone": "12345678"
  }
}'

識別用戶信息 identify

接口説明

identify接口用於識別用戶身份並更新用戶畫像信息，建立完整的用戶檔案。

請求信息

請求URL：https://cdp.cs.topkee.com/v1/identify

請求方法：POST

請求參數

字段	類型	必須	描述
traits	OBJECT	是	用戶特徵信息，包含郵箱、電話等畫像數據

請求示例

curl -X 'POST' \
  'https://cdp.cs.topkee.com/v1/identify' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "identify",
  "api_key": "your_api_key_here",
  "msg_id": "unique_identify_id_456",
  "user_id": "user_12345",
  "traits": {
    "email": "user@example.com",
    "name": "張三",
    "phone": "8613812345678",
    "company": "示例公司"
  },
  "timestamp": "1767174918"
}'

管理用戶別名 Alias

接口說明

alias接口用於合併用戶的不同身份標識，解決用戶多設備、多身份問題。

請求信息

請求URL：https://cdp.cs.topkee.com/v1/alias

請求方法：POST

請求參數

字段	類型	必須	描述
previous_id	STRING	是	原有的用戶身份標識

請求示例

curl -X 'POST' \
  'https://cdp.cs.topkee.com/v1/alias' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "alias",
  "api_key": "your_api_key_here",
  "msg_id": "unique_alias_id_789",
  "user_id": "registered_user_123",
  "previous_id": "anonymous_session_456",
  "timestamp": "1767174918"
}'

查詢項目配置 Settings

接口說明

settings接口用於查詢指定項目的配置信息，包括數據源設置和目的地配置。

請求信息

請求URL：https://cdp.cs.topkee.com/v1/settings

請求方法：POST

請求參數

無特殊請求參數。

請求示例

curl -X 'POST' \
  'https://cdp.cs.topkee.com/v1/settings?api_key=your_api_key_here' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

應答

具體請求結構，應答結構，以及接口測試，可參閲接口文檔： TTO CDP API - Swagger