• API 레퍼런스

Server-to-Server Events

Server-to-Server 방식으로 인앱/인웹 이벤트를 전송할 수 있습니다.

인앱 이벤트 전송하기

POST

https://api.airbridge.io/events/v1/apps/{app_name}/mobile-app/9360

Server-to-Server 방식으로 인앱 이벤트를 전송합니다.

rate limit : 분당 1000회 요청으로 제한됩니다.

유저 식별자 유형

유저 식별자는 일관적인 기여, 포스트백, 코호트 집계 등에 필수적이며 이에 따라 수집 가능한 모든 식별자를 전송하는 것이 권장됩니다.

1. Device ID

Device ID는 SDK를 통한 데이터 패칭(Data Fetching)으로 수집할 수 있습니다.
운영체제별로 수집 가능한 식별자는 다음과 같습니다.

2. User ID(user.externalUserID)

SDK를 통한 데이터 패칭이 불가능한 상황에서는, Device ID 없이 User ID만 전송할 수 있습니다.
이 경우 Airbridge는 내부 데이터베이스를 이용해 해당 User ID와 연결된 Device ID를 기준으로 이벤트를 처리합니다.
하지만 User ID와 연결된 Device ID가 없는 경우, 리포트의 정확도가 떨어질 수 있습니다.

매체 연동 시 주의사항

광고 최적화를 위해 필요한 정보

매체 연동을 이용하는 경우, API로 전송되는 정보가 광고 최적화 목적으로도 사용됩니다.
이에 따라 수집 가능한 모든 정보를 API를 통해 전송하는 것이 권장됩니다.
가장 일반적으로 최적화에 사용되는 정보는 아래와 같습니다.

  • app.packageName

  • device.osName

  • device.osVersion

  • device.appTrackingTransparency

  • device.limitAdTracking

이벤트 예시

Request

Headers

Accept-Language
string

API 요청 및 결과 반환에 사용할 언어를 지정할 수 있습니다. ISO-639-1 포맷을 따릅니다.

Content-Type
string

리소스의 미디어 타입을 나타냅니다. 기본값으로 application/json을 사용합니다.

Authorization
string

API 요청에 사용하는 키값입니다. 키값 생성 및 조회 방법을 확인하여 획득할 수 있습니다.

X-Forwarded-For
필수string

사용자의 IP를 X-Forwarded-For 헤더로 보낼 수 있습니다. X-Forwarded-For가 없는 경우 사용자의 IP(클라이언트 요청 IP)가 아닌 Server To Server API를 요청한 서버의 IP로 사용자 행동이 기록됩니다.

ipv4(123.123.123.123), ipv6(2001:e60:87e3:81d4:cd57:5d52:ee2e:ff8d) 형태의 값을 받습니다.

Path Params

app_name
필수string

에어브릿지 앱 이름(App Name)

Body Params

eventUUID
string

고유 이벤트 ID.

uuid4 포맷의 event uuid는 이벤트 고유 ID로 Deduplication에 사용되며, 넣지 않으면 event api에서 자동 생성하게 됩니다.

eventTimestamp
number

이벤트 발생 시간. (기본값: 현재 시간)

Millisecond 단위의 Unix Timestamp입니다. (Unixtime 기준 13자리)

eventTimestamp가 이벤트 전송 시점 기준으로 24시간을 지나면 서버에서 처리하지 않습니다.

user
object

유저에 관한 정보를 담을 수 있습니다.

device
조건부 필수object

디바이스 정보를 담습니다.

*user.externalUserID를 전송하지 않는 경우 필수로 전송되어야합니다.

app
필수object

사용자의 앱 정보를 담습니다.

eventData
필수object

에어브릿지에 전송할 이벤트를 정의하는 객체입니다.

Request
curl -X POST 'https://api.airbridge.io/events/v1/apps/{app_name}/mobile-app/9360' \ -H 'Accept-Language: ko' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}' \ -H 'X-Forwarded-For: 2001:e60:87e3:81d4:cd57:5d52:ee2e:ff8d' \ -d '{"eventUUID":"9b4b3e4e-2162-4ae6-8986-91ee84644262","user":{"externalUserID":"19443","externalUserEmail":"example@ab180.co","externalUserPhone":"821012341234"},"device":{"deviceUUID":"2dfca632-86f3-4d22-9746-cdfe7985c471","gaid":"2dfca632-86f3-4d22-9746-cdfe7985c471","ifa":"542177F1-5C23-438B-8088-82D34C94F6D7","appSetID":"7c4681ef-97c6-4ebd-9c04-e22f584b3746","ifv":"37EEC3E0-BF15-412E-ADBA-7D2E82E7A75F","limitAdTracking":true,"deviceModel":"LG-H542","appTrackingTransparency":0,"deviceIdentifier":"iPhone11,2","manufacturer":"Samsung","osName":"Android","osVersion":"5.0.2","locale":"ko-KR","timezone":"Asia/Seoul","orientation":"portrait","screen":{"width":123}},"app":{"packageName":"com.ab180.co","version":"1.2.3"},"eventData":{"goal":{"category":"airbridge.ecommerce.product.addedToCart","value":159990,"semanticAttributes":{"currency":"KRW","action":"shoes","label":"nike","transactionID":"12939172","inAppPurchased":true,"products":[{"currency":"KRW","productID":"30372425","price":10990,"name":"나이키 커스텀","position":"1","quantity":1}]}}}}'
Payload
{ "eventUUID": "9b4b3e4e-2162-4ae6-8986-91ee84644262", "user": { "externalUserID": "19443", "externalUserEmail": "example@ab180.co", "externalUserPhone": "821012341234" }, "device": { "deviceUUID": "2dfca632-86f3-4d22-9746-cdfe7985c471", "gaid": "2dfca632-86f3-4d22-9746-cdfe7985c471", "ifa": "542177F1-5C23-438B-8088-82D34C94F6D7", "appSetID": "7c4681ef-97c6-4ebd-9c04-e22f584b3746", "ifv": "37EEC3E0-BF15-412E-ADBA-7D2E82E7A75F", "limitAdTracking": true, "deviceModel": "LG-H542", "appTrackingTransparency": 0, "deviceIdentifier": "iPhone11,2", "manufacturer": "Samsung", "osName": "Android", "osVersion": "5.0.2", "locale": "ko-KR", "timezone": "Asia/Seoul", "orientation": "portrait", "screen": { "width": 123 } }, "app": { "packageName": "com.ab180.co", "version": "1.2.3" }, "eventData": { "goal": { "category": "airbridge.ecommerce.product.addedToCart", "value": 159990, "semanticAttributes": { "currency": "KRW", "action": "shoes", "label": "nike", "transactionID": "12939172", "inAppPurchased": true, "products": [ { "currency": "KRW", "productID": "30372425", "price": 10990, "name": "나이키 커스텀", "position": "1", "quantity": 1 } ] } } }}

Response

200SUCCESS

400ERROR

잘못된 요청 시. (timestamp, sdk signature, app name 등)

401ERROR

잘못된 인증 토큰 사용 시.

Response
{ "at": "2020-02-06 16:06:49", "data": "Event(9360) is successfully proccessed."}
Response
{ "at": "2020-02-06 16:06:49", "error": "invalid_request", "ingested": 0}
Response
{ "at": "2020-02-06 16:06:49", "error": "unauthorized", "ingested": 0}

인웹 이벤트 전송하기

POST

https://api.airbridge.io/events/v1/apps/{app_name}/web/9320

Server-to-Server 방식으로 인웹 이벤트를 전송합니다.

rate limit : 분당 1000회 요청으로 제한됩니다.

유저 식별자 유형

유저 식별자는 일관적인 기여, 포스트백, 코호트 집계 등에 필수적이며 이에 따라 수집 가능한 모든 식별자를 전송하는 것이 권장됩니다.

Cookie ID는 SDK를 통한 데이터 패칭(Data Fetching)으로 수집할 수 있습니다.
이 때 Cookie ID와 함께 아래 데이터를 수집하여 Airbridge 서버로 전송해야 정확히 기여처리 될 수 있습니다.

II. User ID(user.externalUserID)

데이터 패칭이 불가능한 상황에서는, Cookie ID 없이 User ID만 전송할 수 있습니다.
이 경우 Airbridge는 내부 데이터베이스를 이용해 해당 User ID와 연결된 Cookie ID를 기준으로 이벤트를 처리합니다.
하지만 User ID와 연결된 Cookie ID가 없는 경우, 리포트의 정확도가 떨어질 수 있습니다.

Request

Headers

Accept-Language
string

API 요청 및 결과 반환에 사용할 언어를 지정할 수 있습니다. ISO-639-1 포맷을 따릅니다.

Content-Type
string

리소스의 미디어 타입을 나타냅니다. 기본값으로 application/json을 사용합니다.

Authorization
string

API 요청에 사용하는 키값입니다. 키값 생성 및 조회 방법을 확인하여 획득할 수 있습니다.

X-Forwarded-For
필수string

사용자의 IP를 X-Forwarded-For 헤더로 보낼 수 있습니다. X-Forwarded-For가 없는 경우 사용자의 IP(클라이언트 요청 IP)가 아닌 Server To Server API를 요청한 서버의 IP로 사용자 행동이 기록됩니다.

ipv4(123.123.123.123), ipv6(2001:e60:87e3:81d4:cd57:5d52:ee2e:ff8d) 형태의 값을 받습니다.

Path Params

app_name
필수string

에어브릿지 앱 이름(App Name)

Body Params

eventUUID
string

고유 이벤트 ID.

uuid4 포맷의 event uuid는 이벤트 고유 ID로 Deduplication에 사용되며, 넣지 않으면 event api에서 자동 생성하게 됩니다.

eventTimestamp
number

이벤트 발생 시간. (기본값: 현재 시간)

Millisecond 단위의 Unix Timestamp입니다. (Unixtime 기준 13자리)

eventTimestamp가 이벤트 전송 시점 기준으로 24시간을 지나면 서버에서 처리하지 않습니다.

user
object

유저에 관한 정보를 담을 수 있습니다.

browser
object

브라우저 정보를 담을 수 있습니다.

eventData
필수object

에어브릿지에 전송할 이벤트를 정의하는 객체입니다.

Request
curl -X POST 'https://api.airbridge.io/events/v1/apps/{app_name}/web/9320' \ -H 'Accept-Language: ko' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}' \ -H 'X-Forwarded-For: 2001:e60:87e3:81d4:cd57:5d52:ee2e:ff8d' \ -d '{"eventUUID":"9b4b3e4e-2162-4ae6-8986-91ee84644262","user":{"externalUserID":"19443","externalUserEmail":"example@ab180.co","externalUserPhone":"821012341234"},"browser":{"clientID":"05609013-bb5a-4594-bbc3-832cb1b87072","userAgent":"Mozilla/5.0 (iPhone; CPU iPhone OS 11_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E302"},"eventData":{"shortID":"aef04","trackingData":{"channel":"blog"},"goal":{"category":"airbridge.ecommerce.product.addedToCart","value":159990,"semanticAttributes":{"action":"shoes","label":"nike","query":"나이키","transactionID":"12939172","inAppPurchased":true,"currency":"KRW","products":[{"position":"1","productID":"30372425","name":"나이키 커스텀","price":10990,"quantity":1,"currency":"KRW"}]}}}}'
Payload
{ "eventUUID": "9b4b3e4e-2162-4ae6-8986-91ee84644262", "user": { "externalUserID": "19443", "externalUserEmail": "example@ab180.co", "externalUserPhone": "821012341234" }, "browser": { "clientID": "05609013-bb5a-4594-bbc3-832cb1b87072", "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E302" }, "eventData": { "shortID": "aef04", "trackingData": { "channel": "blog" }, "goal": { "category": "airbridge.ecommerce.product.addedToCart", "value": 159990, "semanticAttributes": { "action": "shoes", "label": "nike", "query": "나이키", "transactionID": "12939172", "inAppPurchased": true, "currency": "KRW", "products": [ { "position": "1", "productID": "30372425", "name": "나이키 커스텀", "price": 10990, "quantity": 1, "currency": "KRW" } ] } } }}

Response

200SUCCESS

400ERROR

잘못된 요청 시. (timestamp, sdk signature, app name 등)

401ERROR

잘못된 인증 토큰 사용 시.

Response
{ "at": "2020-02-06 16:06:49", "data": "Event(9320) is successfully proccessed."}
Response
{ "at": "2020-02-06 16:06:49", "error": "invalid_request", "ingested": 0}
Response
{ "at": "2020-02-06 16:06:49", "error": "unauthorized", "ingested": 0}