인웹 이벤트 전송하기

curl -X POST 'https://api.airbridge.io/events/v2/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": {
    "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"
          }
        ]
      }
    }
  }
}'

{
  "at": "2020-02-06 16:06:49",
  "data": "Event(9320) is successfully proccessed."
}

{
  "at": "2020-02-06 16:06:49",
  "error": "invalid_request",
  "ingested": 0
}

{
  "at": "2020-02-06 16:06:49",
  "error": "unauthorized",
  "ingested": 0
}

Server-to-Server 방식으로 인웹 이벤트를 전송합니다. rate limit : 분당 1000회 요청으로 제한됩니다.

유저 식별자 유형

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

Cookie ID는 SDK를 통한 데이터 패칭(Data Fetching)으로 수집할 수 있습니다. 이 때 Cookie ID와 함께 기여정보를 Airbridge 서버로 전송해야 정확히 기여처리 될 수 있습니다. 기여정보는 Web SDK fetchResource 콜백의 resource.attributionData에서 가져옵니다. 자세한 내용은 데이터 패칭 - 웹을 확인하세요.

파라미터	입력할 값
`eventData.shortID`	`resource.attributionData.shortID`
`eventData.trackingData`	`resource.attributionData.trackingData` 객체 전체
`eventData.goal`	전송할 이벤트 정보를 직접 입력합니다.
`attributionData`	`resource.attributionData`

attributionData는 요청 최상위에서 eventData와 같은 레벨에 둡니다. eventData.shortID와 eventData.trackingData도 함께 전송하세요.

attributionData는 기여에 필요한 데이터입니다. 이 데이터를 수정하지 않도록 주의하세요.

airbridge.fetchResource(function(resource) {
    const attributionData = resource.attributionData

    const body = {
        browser: {
            clientID: resource.browser.clientID,
            userAgent: resource.browser.userAgent,
        },
        eventData: {
            shortID: attributionData.shortID,
            trackingData: attributionData.trackingData,
            goal: {
                category: "airbridge.ecommerce.order.completed",
            },
        },
        attributionData: attributionData,
    }

    // body를 서버로 전달해 S2S API 요청 본문에 사용합니다.
})

전송 예시

{
  ...

  "browser": {
    "clientID": "05609013-bb5a-4594-bbc3-832cb1b87072"
  },
  "eventData": {
    "shortID": "aef04",
    "trackingData": {
      "channel": "blog",
      "params": {
        "ad_creative": "ad_creative",
        "ad_group": "ad_group",
        "campaign": "ad_campaign",
        "content": "ad_content",
        "medium": "ad_medium",
        "tracking_template_id": "ad_tracking_template_id"
      }
    }
  },
  "attributionData": { ... },
  "user": {
    "externalUserID": "19443",
    "externalUserEmail": "example@ab180.co",
    "externalUserPhone": "821012341234"
  }
  
  ...
}

II⁠. User ID(`user.externalUserID`)

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

전송 예시

{
    ...
    
    "user": {
        "externalUserID": "19443",
        "externalUserEmail": "example@ab180.co",
        "externalUserPhone": "821012341234"
    }

    ...
}

POST

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

Request

Headers

string

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

string

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

string

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

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

string

필수

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

Body Params

string

고유 이벤트 ID.uuid4 포맷의 event uuid는 이벤트 고유 ID입니다. 넣지 않으면 event api에서 자동 생성하게 됩니다.

number

이벤트 발생 시간. (기본값: 현재 시간)Millisecond 단위의 Unix Timestamp입니다. (Unixtime 기준 13자리)eventTimestamp가 이벤트 전송 시점 기준으로 24시간을 지나면 서버에서 처리하지 않습니다.

object

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

표시 하위 변수

string

사용자 아이디.Required when: device.deviceUUID를 전송하지 않는 경우 필수로 전송되어야합니다.

string

사용자 이메일.

string

사용자 전화번호.

object

커스텀 사용자 속성.JSON 형태의 데이터를 받습니다.{ "age_group": "30", "brand": "Nike" }

object

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

표시 하위 변수

string

필수

브라우저 쿠키 아이디. SDK에서 Fetching한 값이 필요합니다. 관련 문서Data Fetching이 불가능한 경우 User ID(user.externalUserID)를 전송하는 조건으로 생략할 수 있습니다.

string

브라우저의 유저 에이전트.해당 값은 이벤트의 운영체제(OS Name, Version), 플랫폼(Platform)을 결정하는 것에 사용되며, Data Fetching을 통해 수집할 수 있습니다. 관련 문서

object

필수

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

표시 하위 변수

string

필수

어트리뷰션 캠페인 파라미터 ID. SDK Data Fetching을 통해 획득한 resource.attributionData.shortID 값을 전송하여야합니다.중요: 이 값은 처리나 여과 없이 에어브릿지 서버로 전송되어야합니다.Data Fetching이 불가능한 경우 User ID(user.externalUserID)를 전송하는 조건으로 생략할 수 있습니다.

object

필수

에어브릿지의 어트리뷰션에 적용할 데이터를 담을 수 있습니다.SDK Data Fetching을 통해 획득한 resource.attributionData.trackingData 객체를 하위 필드를 나누지 않고 그대로 전송하여야합니다.

표시 하위 변수

string

필수

어트리뷰션 캠페인 채널. SDK Data Fetching을 통해 획득한 값을 전송하여야합니다.중요: 이 값은 처리나 여과 없이 에어브릿지 서버로 전송되어야합니다. (eg. airbridge.websdk와 같은 값도 전송되어야합니다)Data Fetching이 불가능한 경우 User ID(user.externalUserID)를 전송하는 조건으로 생략할 수 있습니다.

object

필수

어트리뷰션 캠페인 파라미터.{"medium: "posting", campaign: "blog", term: "airbridge", content: "martech-solution"}SDK Data Fetching을 통해 획득한 값을 전송하여야합니다.중요: 이 값은 처리나 여과 없이 에어브릿지 서버로 전송되어야합니다.Data Fetching이 불가능한 경우 User ID(user.externalUserID)를 전송하는 조건으로 생략할 수 있습니다.

object

필수

이벤트에 관한 정보를 담을 수 있는 객체입니다.카테고리, 액션, 라벨, 밸류, 시맨틱 어트리뷰트(Semantic Attributes)를 담을 수 있습니다.(관련 가이드)

표시 하위 변수

string

필수

에어브릿지 이벤트의 카테고리. 이벤트 이름과 동일합니다. (관련 가이드)

number

이벤트의 가치.상품 구매, 조회 이벤트의 상품 가격이나, Ad Impression의 광고 수익과 같은 정보를 표현할 수 있습니다.

object

커스텀 이벤트 속성.{ "color": "red" }

object

Semantic Attributes. 에어브릿지가 수집할 데이터를 미리 정의한 속성입니다.

표시 하위 변수

string

에어브릿지 이벤트의 첫 번째 프로퍼티

string

에어브릿지 이벤트의 두 번째 프로퍼티

string

사용자 검색 쿼리.

string

상품 리스트 ID.

string

장바구니 ID.

string

거래 고유번호.

boolean

In-app 구매 여부.

true : In-app 구매
false : In-app 구매 아님

string

결제 이벤트의 결제 통화. 이벤트 처리 과정에서 대시보드에 설정된 통화로 변환되므로 실제 결제에 사용된 통화를 사용해도 됩니다.

object[]

상품에 대한 정보를 리스트로 담을 수 있습니다.

표시 하위 변수

string

상품 위치.

string

상품 ID.

string

상품 이름.

number

상품 가격.

integer

상품 수량.

string

상품 가격의 통화

object

기여에 필요한 데이터입니다. SDK Data Fetching을 통해 획득한 resource.attributionData를 전송하여야합니다. (관련 문서)eventData와 같은 레벨에 둡니다.중요: 이 데이터를 수정하지 않도록 주의하여야합니다.Data Fetching이 불가능한 경우 User ID(user.externalUserID)를 전송하는 조건으로 생략할 수 있습니다.

curl -X POST 'https://api.airbridge.io/events/v2/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": {
    "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

200

400

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

401

잘못된 인증 토큰 사용 시.

{
  "at": "2020-02-06 16:06:49",
  "data": "Event(9320) is successfully proccessed."
}

{
  "at": "2020-02-06 16:06:49",
  "error": "invalid_request",
  "ingested": 0
}

{
  "at": "2020-02-06 16:06:49",
  "error": "unauthorized",
  "ingested": 0
}

API Reference

Tracking Link

Server-to-Server Events

Actuals Report

Revenue Report

Retention Report

Active Users Report

Raw Data

Attribution Result

Self-Serve Data Upload

SKAdNetwork Configuration API

유저 식별자 유형

II⁠. User ID(`user.externalUserID`)

Request

Headers

Path Params

Body Params

Response

200

400

401

유저 식별자 유형

I⁠. Cookie ID(browser.clientID)

II⁠. User ID(user.externalUserID)

Request

Headers

Path Params

Body Params

Response

200

400

401

I⁠. Cookie ID(`browser.clientID`)

II⁠. User ID(`user.externalUserID`)