한눈에 보기: 웹 서버 대 서버(Web-S2S) 이벤트 API를 이용하여 웹 SDK로 리포트되지 않는 이벤트와 전환을 PBA에 리포트하세요.
PBA용 웹 서버 대 서버 이벤트 API
웹-S2S API는 웹 SDK를 보완하여 마케터가 웹사이트에서 발생하지만 웹 SDK 범위 바깥에서 일어나는 이벤트를 리포트할 수 있게 해줍니다. 예를 들어 웹사이트 방문자(웹 유저)가 온라인 결제 이벤트를 유발하고 이벤트는 백엔드 시스템에 의해 처리됩니다. 처리를 마친 후 백엔드는 S2S API를 활용해 앱스플라이어에 이벤트를 리포트합니다.
S2S API를 통해 전송된 이벤트는:
- 웹 SDK로 리포트된 이벤트와 마찬가지로 기록됩니다.
- 전환 이벤트로 설정될 경우 PBA 대시보드에 포함됩니다.
- event_source 필드를 웹 S2S로 설정하여 PBA 로데이터를 채웁니다.
API 사용법
다음 섹션을 활용해 API 호출을 만드십시오.
| 아닙니다. | 아이템 | 설명 |
|---|---|---|
| 1 | 고유 사용자 ID | |
| 2 | Timestamp |
|
| 3 | 수익 및 화폐 단위 | 이벤트 값에 포함될지라도 반드시 eventRevenueCurrency와 eventRevenue를 기입해야 합니다. 대시보드에서 이 정보들을 활용하기 때문에 필수적입니다. |
API 기초
API 구현 시 대시보드에서 제공되는 다음 인증 정보들이 필요합니다:
- 번들 ID(브랜드 번들 ID로도 알려져 있음)
- 웹 개발자 키
인증 정보를 얻으려면:
- 앱스플라이어의 상단 메뉴에서 내 앱 > 브랜드 번들 보기를 선택하세요.
번들 목록이 나타납니다. - 다음 항목들을 복사해서 기록하세요:
- 브랜드 번들 ID
- 웹 개발자 키
웹 S2S API의 기본 사항
| 경로 |
|
| HTTP 메서드 | POST |
| 허용된 콘텐츠 타입 |
application/json |
| JSON 페이로드 제한 |
JSON 페이로드 크기: 최대 1KB |
| 콜 수 제한 |
POST 제한: 분당 60,000건의 POST. 한도 증가를 원하면 CSM에 연락하세요. |
| TLS |
|
setCuId 메소드
| 메소드 명 |
setCuId |
| 적용 케이스 |
방문자의 CUID와 연결할 때. 예를 들어, 언제든지 귀사의 고객 사용자 ID와 웹 |
| 메소드 경로 |
|
| 페이로드 |
JSON 페이로드는 여기에 나열된 파라미터들로 구성됩니다. 모든 파라미터는 필수항목입니다. |
Curl 예제 setCuId
curl --location --request POST 'https://webs2s.appsflyer.com/v1/bundleId/setcuid' \
--header 'Accept-Encoding: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"customerUserId": "1234567890abcdef",
"afUserId":"9999999-f848-4963-a091-568f0bf9a361",
"webDevKey" : "99999999-9999-9999-9999-999999999999"}이벤트 메서드
| 메소드 명 |
이벤트 |
| 적용 케이스 | 보내기 |
| 메소드 경로 |
|
| 상세한 정보 | 이 문서의 이벤트 메소드 세부 정보 섹션에는 페이로드 상세 정보, Curl 예제, Python 예제 및 테스팅 제안이 포함되어 있습니다. |
이벤트 메소드 상세 정보
페이로드(payload) 파라미터
페이로드 파라미터는 사용자 식별자 및 이벤트 파라미터로 구분됩니다.
- 유저 ID: 최소한 하나 이상의 사용자 ID 파라미터를 전송해야 합니다.
- 이벤트: 필수 파라미터와 필요에 따라 선택적 파라미터를 전송하세요.
사용자 식별자 파라미터(최소 한 개 이상 전송해야 함)
| 사용자 ID 파라미터 | 설명 |
|---|---|
|
customerUserId |
고객 사용자 ID(CUID)는 귀하가 지정한 고유 식별자입니다.
|
|
afUserId |
웹 SDK를 통해 방문하는 모든 사용자에게 할당된 고유 사용자 ID입니다. 쿠키 값을 귀사의 백엔드 서버로 전달해야 합니다.
|
이벤트 파라미터
| 파라미터 이름 | 필수적 | 설명 |
|---|---|---|
|
webDevKey |
예 |
대시보드에서 제공되는 웹 개발자 키를 사용하여 채웁니다.
|
| 이벤트 유형 | 예 |
앱스플라이어 내부용 이벤트 속성 식별자. 항상 EVENT.로 설정해야 합니다.
|
| eventName | 예 |
|
| 타임 스탬프 | 아니오 |
이벤트 발생 시간(밀리초 단위). 13자리 Unix 타임스탬프 형식으로 보내세요.
|
| eventValue | 아니오 |
이벤트를 설명하는 이벤트 파라미터의 집합입니다. 제품 SKU, 개별 항목 가격과 같은 리치 인앱 이벤트 전송에 이 파라미터를 사용하세요.
|
| eventRevenueCurrency | 아니오 |
수익 이벤트의 통화 코드는 3자리 ISO 4217 통화 코드를 사용합니다.
|
| 이벤트 수익 | 아니오 |
이벤트에 할당된 수익(금액). 일러두기! 수익을 eventValue에 보고할 때는 eventRevenue에도 보고하고, eventRevenueCurrency도 함께 기입해야 합니다.
|
| 아니오 | 이 파라미터는 더 이상 사용되지 않으며, 앞으로 시스템에서 제거될 예정입니다. 대신에 eventValue를 사용해주세요. | |
| 아니오 |
이 파라미터는 더 이상 사용되지 않으며, 앞으로 시스템에서 제거될 예정입니다. 대신에 eventValue를 사용해주세요. |
|
| 리퍼러 | 아니오 |
HTTP 리퍼러
|
| userAgent | 아니오 |
유저 에이전트 요청은 브라우저가 서버로 보낸 요청입니다.
|
| ip | 아니오 |
사용자 IP 주소
|
curl 예시
curl --location --request POST 'https://webs2s.appsflyer.com/v1/bundleId/event' \
--header 'Accept-Encoding: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"customerUserId": "1234567890abcdef",
"afUserId":"9999999-f848-4963-a091-568f0bf9a361",
"webDevKey" : "99999999-9999-9999-9999-999999999999",
"ip" : "192.0.2.1",
"eventType":"EVENT",
"timestamp" : 1234567890123,
"eventName":"my_web_event",
"eventRevenueCurrency" : "EUR",
"eventRevenue" : 1234.56,
"eventValue": {
"purchase":{
"shoes": "color",
"quantity" : "3",
"Revenue" : "1234.56",
"Currency" : "ZAR"
}
}
}'Python 예제
''' using the requests python package, install using pip install requests '''
import requests
url = "https://webs2s.appsflyer.com/v1/bundleId/event"
payload = {
"customerUserId": "1234567890abcdef",
"afUserId": "9999999-f848-4963-a091-568f0bf9a361",
"webDevKey": "99999999-9999-9999-9999-999999999999",
"ip": "192.0.2.1",
"eventType": "EVENT",
"timestamp": 1234567890123,
"eventName": "my_web_event",
"eventRevenenuCurrency": "EUR",
"eventRevenue": 1234.56,
"eventValue":
{
"purchase":
{
"shoes": "color",
"quantity": "3",
"Revenue": "1234.56",
"Currency": "ZAR"
}
}
}
headers = {
'Accept-Encoding': 'application/json',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.text.encode('utf8'))
테스트
테스트를 위해 다음과 같이 여러 이벤트를 전송하세요:
- 이벤트를 전송합니다.
- 200 OK 응답 코드를 받았는지 확인하세요. 만약 그렇지 않다면, 복구 조치를 위해 반환 코드와 오류 메시지를 사용하세요.
- UTC 자정이 지난 후 몇 시간을 기다렸다가 PBA 로데이터에서 보고된 이벤트를 확인하시기 바랍니다. PBA 데이터는 일일 기준으로 처리되므로, 기다려야 합니다.
추가 정보
웹 개발 키를 가져오는 방법
웹 개발 키를 가져오는 방법:
- AppsFlyer에서내 앱탭으로 이동하세요.
- '브랜드 번들 보기'를 클릭하세요.
- 필요한 웹 개발 키를 복사하세요.
웹 SDK에서 afUserID 추출
- afUserID는 귀하의 웹사이트를 사용자가 첫 방문했을 때 웹 SDK에 의해 부여되는 고유 식별자입니다.
- 필요한 경우 아래 방법 중 하나를 사용하세요.
HTTP 쿠키 헤더에서 afUserId 획득
- 방문자의 브라우저가 귀하의 사이트로 요청을 보낼 때
afUserId이(가) 전송됩니다. - 필요하다면 HTTP 쿠키 헤더에서 추출하십시오.
방문자 브라우저에서 afUserId 확인
- 방문자의 브라우저에서 afUserID를 확인하여 문제를 해결하거나 디버깅할 수 있습니다.
- 이를 확인하기 위해 방문자는 최소 한 번 웹 SDK가 있는 페이지를 방문해야 합니다.
afUserId을(를) 포함하는 쿠키는 귀사의 도메인과 관련된 자사 쿠키입니다.- 이 절차는 크롬 버전 81을 기반으로 준비되었습니다. 브라우저 및 운영 체제에 따라 차이가 있을 수 있습니다.
방문자 브라우저에서 afUserId 가져오는 방법:
- 브라우저에서 귀하의 웹사이트로 이동하십시오.
-
'검사'를 선택하기 위해 마우스 오른쪽 버튼을 클릭하세요
브라우저의 요소 검사 창이 나타납니다. - '애플리케이션(Application)' 탭으로 이동하세요.
- 측면 메뉴에서 '쿠키(Cookies)'를 확장하세요.
- 귀하의 웹사이트를 선택하세요. 보이지 않는다면 브라우저를 새로고침하세요.
- (C) 필터 필드에
afUserId을(를)}입력하세요.
afUserID의 값이 나타납니다.
응답 코드
| 응답 코드 | 메시지 | 처리 방법 |
|---|---|---|
| 200 | OK | |
| 404 | Not found |
|
| 400 | Bad request |
|
문제 해결
- 증상: HTTP 반환 코드가 반환되지 않습니다.
해결 방안: 앱스플라이어 서버를 허용 목록에 추가하십시오.
릴리즈 노트
| Date (날짜) | 엔드포인트 버전 | 참고 |
|---|---|---|
| 2020-05-12 | 1 | 초판 |
| 2020-05-24 | 1 | |
| * 버전 번호는 엔드포인트의 버전 번호를 나타냅니다. | ||