ironSource 데이터 연동 솔루션
최종 업데이트 날짜: 2022-08-17
1. 개요
서드파티 데이터 통합으로 생성된 데이터는 클러스터의 소비 데이터양에 포함됩니다
이 문서에서는 ironSource 데이터를 Agentic Engine(이하 AE 시스템)으로 콜백하는 방법을 소개합니다. 이 계획은 다음을 지원합니다:
- 클라이언트 SDK로 데이터를 전송하면 수익 데이터를 실시간으로 가져올 수 있지만, 이 수익 데이터는 추정값이므로 최종 정산 데이터와 약간 차이가 있습니다
- Impression Level Revenue API로 더 정확한 수익 데이터를 가져올 수 있지만 실시간성이 떨어집니다(T+1에 수익 데이터를, T+2에 최종 데이터를 가져올 수 있음)
- Reporting API로 노출, 수익, 유저 활성 등의 집계 지표 데이터를 가져옵니다.
ironSource 연동을 시작하기 전에 AE 시스템의 데이터 규칙을 읽고 AE의 데이터 구조를 이해했는지 확인하십시오. 또한 데이터 수집에 필요한 정보를 저희 고객 성공 매니저에게 전달하는 것을 권장합니다. 형식은 데이터 연동 설정 정보 템플릿을 참고하십시오.
2. 클라이언트 SDK 전송
인터페이스 기본 정보
| 인터페이스명 | API 타입 | 제품화 | 데이터 세분화 | 어트리뷰션 데이터 | 비용 데이터 | 수익 데이터 | 노출 데이터 | 클릭 데이터 | 전환 데이터 |
|---|---|---|---|---|---|---|---|---|---|
| ILR SDK | 클라이언트 SDK | 아니요 | 유저 수준 | 예 |
Impression Level Revenue (ILR) SDK API는 ironSource SDK의 실시간 수익 인터페이스로, ironSource 클라이언트 SDK(Android, iOS, Unity SDK) 7.0.3 이상 버전에서 제공됩니다. 이 인터페이스는 광고가 노출된 후 콜백으로 예상 수익 데이터를 실시간으로 가져오며, 이를 AE 클라이언트 SDK로 전송하면 실시간성이 매우 높은 수익 데이터를 얻을 수 있습니다.
2.1 ironSource 설정
ILR SDK의 실시간 수익 콜백 기능을 활성화하려면 먼저 ironSource 백엔드에 로그인하여 My Account - API 페이지의 ARM SDK Postbacks 항목에서 Enable ad revenue measurements (ARM) SDK postbacks를 체크해야 합니다
2.2 AE 클라이언트 SDK 설정
방안 1(자동 통합):
연동한 AE SDK 버전이 2.8.0~2.8.1이면 자동 연결 방안을 사용하는 것을 권장합니다
연동한 AE SDK 버전이 2.8.2 이상이면 서드파티 데이터 플러그인도 설치해야 합니다
이 방안은 자동 통합 방안입니다. AE 클라이언트 SDK를 초기화한 후 다음 코드를 호출하여 활성화하십시오. 자세한 내용은 Android SDK 서드파티 데이터 및 iOS SDK 서드파티 데이터를 참고하십시오
// AE SDK 초기화
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
// ironSource id 연결 활성화
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_IRON_SOURCE);
// ironSource SDK 초기화
// ...
이 방안의 원리는 내부에서 onImpressionSuccessEvent 콜백을 자동으로 등록하고, 콜백을 받으면 IronSourceImpressionData의 파라미터를 자동으로 파싱한 다음 AE SDK로 ta_ironSource_callback 이벤트를 전송하는 것입니다
방안 2(수동 통합):
수동 통합 방안에서는 ImpressionData Listener를 구현하고 그 안에 AE SDK의 데이터 전송 인터페이스를 추가해야 합니다. 다음은 Unity 코드 예시로, ImpressionSuccessEvent()를 구현하여 onImpressionSuccessEvent에 등록하면 광고가 노출된 후 콜백이 트리거되어 데이터가 전송됩니다. 각 SDK의 구현 방식을 알아보려면 다음 링크를 참고하십시오:
// ImpressionSuccessEvent를 등록하고 그 안에 AE로 데이터를 전송하는 코드 로직을 설정
private void ImpressionSuccessEvent(IronSourceImpressionData impressionData) {
Debug.Log ("unity-script: ImpressionSuccessEvent impressionData = " + impressionData);
if (impressionData != null) {
Dictionary<string, object> properties = new Dictionary<string, object>()
{
// 수익 출처: 광고 유닛
{"adUnit", impressionData.adUnit},
// 수익 출처: 광고 채널
{"adNetwork", impressionData.adNetwork},
// 수익 출처: ironSource 인스턴스 이름
{"instanceName", impressionData.instanceName},
// 수익 출처: ironSource 인스턴스 ID
{"instanceId", impressionData.instanceId},
// Placement
{"placement", impressionData.placement},
// 통화 타입
{"currency", "USD"},
// 수익
{"revenue", impressionData.revenue},
// 수익 타입
{"precision",impressionData.precision}
};
// 수익 데이터를 AE로 전송(수익 이벤트 이름을 ironSource_sdk_postbacks로 가정)
ThinkingAnalyticsAPI.Track("ironSource_sdk_postbacks", properties);
}
}
ironSource SDK Postbacks의 콜백 필드 목록은 다음과 같습니다. ironSource 공식 문서에서도 확인할 수 있습니다:
| 필드 이름 | 설명 | 데이터 타입 |
|---|---|---|
| auctionId | 입찰 고유 식별 ID | String |
| adUnit | 노출된 광고 유닛(예: Rewarded Video, Interstitial, Banner) | String |
| adNetwork | 광고 미디어 채널 이름 | String |
| instanceName | 광고 인스턴스 이름 | String |
| instanceId | 광고 인스턴스 ID | String |
| country | ISO 3166-1 형식의 국가(지역) 코드 | String |
| placement | 광고 게재 위치 | String |
| revenue | 수익 데이터(USD). 이 값은 예상값일 수 있으며, 자세한 내용은 precision 필드의 값을 참고하십시오 | Double |
| precision | revenue 값의 출처:
| String |
| ab | ironSource 백엔드에서 설정한 A/B Test 표시 | String |
| segmentName | 유저가 분류된 트래픽 그룹 이름(즉 Segment, ironSource 백엔드에서 설정) | String |
| lifetimeRevenue | 유저가 누적으로 창출한 수익 | Double |
| encryptedCPM | 이 필드는 Meta Audience Network(즉 Facebook Audience Network)의 광고 데이터에만 있습니다 | String |
3. Impression Level Revenue API
인터페이스 기본 정보
| 인터페이스명 | API 타입 | 제품화 | 데이터 세분화 | 어트리뷰션 데이터 | 비용 데이터 | 수익 데이터 | 노출 데이터 | 클릭 데이터 | 전환 데이터 |
|---|---|---|---|---|---|---|---|---|---|
| Impression Level Revenue API | 풀 방식 | 아니요 | 유저 수준 | 예 | 예 |
Impression Level Revenue API는 노출 수준(impression-level)과 유저 수준(user level)의 두 가지 데이터를 제공합니다. 노출 수준 데이터는 각 데이터가 광고 노출 1회에 해당하므로 이벤트 데이터의 의미에 부합합니다. 반면 유저 수준 데이터는 한 유저의 전체 기간 지표를 집계한 것이므로 이벤트 데이터로 콜백하기에 적합하지 않고, 데이터가 계속 변하기 때문에 AE 시스템에서 처리하고 분석하기에도 적합하지 않습니다. 따라서 노출 수준 데이터의 연동만 지원합니다.
3.1 인증 코드 및 App Key 가져오기
Impression Level Revenue API를 연동하기 전에 먼저 인증 코드와 데이터를 수집할 프로젝트의 App Key를 가져와야 합니다.
- ironSource 백엔드에 로그인하여 오른쪽 상단의 사용자 메뉴를 클릭하고 My Account 페이지의 Reporting API 탭으로 이동한 후 Secret Key와 Refresh Token을 ThinkingAI 담당자에게 보냅니다:
- 다음으로 ironSource 백엔드의 Ad Unit 페이지로 이동하여 APPLICATIONS 목록에서 연동할 앱을 선택하면 오른쪽 카드에 해당 앱의 App Key가 표시됩니다. 이를 ThinkingAI 담당자에게 보내거나 데이터 연동 설정 정보 템플릿에 기록합니다(iOS와 Android는 별개이므로 두 플랫폼의 데이터를 모두 연동하려면 App Key 두 개를 보내야 합니다)
3.2 클라이언트 SDK 설정
ironSource 유저 데이터를 AE 프로젝트와 연결하려면 ironSource의 setUserId() 메서드로 AE 유저의 게스트 ID를 ironSource에 전송해야 합니다. 다음 예시 코드는 Unity SDK를 예로 들어 AE의 게스트 ID를 ironSource의 UserId로 설정합니다:
// AE의 게스트 ID를 ironSource의 User ID로 설정
IronSource.Agent.setUserId(ThinkingAnalyticsAPI.GetDistinctId());
AE 클라이언트 SDK의 기본 게스트 ID 값은 다음과 같습니다:
- Android에서는 AE SDK의 게스트 ID가 GAID이며, ironSource의 advertising_id는 GAID를 사용합니다
- iOS에서는 AE SDK의 게스트 ID가 IDFV이며, ironSource의 advertising_id는 IDFA/IDFV를 사용합니다
3.3 포함 필드
다음은 Impression Level Revenue API가 반환하는 필드입니다:
- 차원 필드
| 필드 이름 | 설명 | 값 예시 |
|---|---|---|
| event_timestamp | 노출 타임스탬프 | 2021-09-01 11:26:46 |
| #zone_offset | 시간대(AE 프리셋 속성) | 0(고정값) |
| advertising_id | 유저의 광고 ID(GAID / IDFA) | 137cf2f0-609c-4ae3-ab64-ed5c0d7392fd |
| advertising_vendor_id | 유저의 Vendor ID(app Set ID / IDFV) | A0810F0B-16C2-474B-B765-77B3A3113AA2 |
| user_id | 유저가 설정한 User ID, 즉 3.2에서 설정한 유저 ID | c7d9fed7-aa40-4bfa-918f-8d4b155bfd4b |
| ad_unit | 광고 유닛 | rewarded_video |
| ad_network | 광고 미디어 | Admob |
| instance_name | 인스턴스 이름 | Bidding, High |
| country | 국가(지역) 코드 | US |
| placement | 게재 위치 | Home_Screen |
| segment | 유저가 분류된 트래픽 그룹 이름 | Tier 1 |
| AB_Testing | A/B Test 태그 | A,B |
| app_key | 앱 Key | |
| app_name | 앱 이름 | |
| platform | 플랫폼 | iOS, android |
- 지표 필드
| 필드 이름 | 설명 | 값 예시 |
|---|---|---|
| impressions | 노출 수 | 1000 |
| revenue | 수익 금액 | 0.5 |
3.4 인터페이스 파라미터
-
시간:
-
일 단위, UTC 시간대의 데이터를 수집합니다
- 최근 14일의 데이터만 수집할 수 있습니다(예: 1월 1일 데이터는 최대 1월 14일까지 보존되며, 그 이후에는 수집해도 데이터가 없음)
- 매일 UTC 시간 오후 2시(베이징 시간 오후 10시)에 전날(UTC 시간대 기준)의 데이터를 가져올 수 있습니다
- 데이터 보정은 지난 2일의 데이터(즉 어제, 그저께)에만 적용되며, 그 이후에는 데이터가 안정되어 더 이상 조정되지 않습니다
-
3.5 데이터 저장 규칙
기본적으로 수집한 데이터는 이벤트 형태로 AE 프로젝트에 기록되며, 노출 데이터 1건이 이벤트 데이터 1건으로 기록됩니다:
- 데이터의 user_id를 데이터의 게스트 ID로 사용합니다. 이 필드는 AE 프로젝트의 게스트 ID와 대응해야 합니다
- 데이터의 event_timestamp 필드, 즉 광고 노출 시간을 이벤트의 #event_time으로 사용합니다
- 데이터 이벤트 이름은 ironsource_ad_revenue_impression_level입니다
- 나머지 필드는 모두 저장됩니다
3.6 데이터 연동 설정 정보 템플릿
위 문서를 읽은 후 다음 정보 템플릿을 작성하여 ThinkingAI의 고객 성공 매니저에게 보내는 것을 권장합니다:
데이터 인터페이스: ironSource Impression Level Revenue API
--------
회사 이름: XXX
AE 프로젝트 환경: (SAAS/프라이빗 배포)
AE 프로젝트 이름: XXX
AE 프로젝트 APP ID: XXX
데이터 수신 주소 push_url: XXX
---------
secretkey: XXX
refreshToken: XXX
---------
데이터 수집 설정
appKey: XXX, XXX(iOS, Android 별도)
과거 데이터 수집 기간: yyyy/mm/dd - yyyy/mm/dd(최근 14일의 데이터만 수집 가능)
정기 수집: 매일 베이징 시간 22시에 전날 데이터 수집
4. Reporting API
인터페이스 기본 정보
| 인터페이스명 | API 타입 | 제품화 | 데이터 세분화 | 어트리뷰션 데이터 | 비용 데이터 | 수익 데이터 | 노출 데이터 | 클릭 데이터 | 전환 데이터 |
|---|---|---|---|---|---|---|---|---|---|
| Reporting API | 풀 방식 | 아니요 | 집계 지표 | 예 | 예 | 예 |
Reporting API는 ironSource의 집계 지표 데이터 인터페이스로, 이 인터페이스로 노출, 수익, 유저 활성 등의 집계 지표 데이터를 가져올 수 있습니다.
4.1 인증 코드 가져오기
Reporting API를 연동하기 전에 먼저 인증 코드를 가져와야 합니다. ironSource 백엔드에 로그인하여 오른쪽 상단의 사용자 메뉴를 클릭하고 My Account 페이지의 Reporting API 탭으로 이동한 후 Secret Key와 Refresh Token을 ThinkingAI 담당자에게 보냅니다:
4.2 포함 필드
다음은 Reporting API가 반환하는 필드입니다:
- 차원 필드
다음은 Reporting API의 분석 차원입니다. 분석 차원마다 지원하는 지표가 다르므로 주의하십시오. 구체적인 대응 관계는 ironSource 공식 문서를 참고하십시오:
| 차원명 | 필드 이름 | 설명 | 기본 여부 | 비고 |
|---|---|---|---|---|
| date | date | 데이터 시간 | 예 | |
| adUnits | adUnits | 광고 유닛 | 예 | |
app | appKey | 앱 Key | 예 | |
| bundleId | 앱 ID | 예 | ||
| appName | 앱 이름 | 예 | ||
| platform | platform | 앱 플랫폼 | 예 | |
| adSource | providerName | 광고 소스 | 예 | |
| instance | instanceName | 인스턴스 이름 | segment, placement와 상호 배타적 | |
| instanceId | 인스턴스 ID | |||
| country | countryCode | 국가(지역) 코드 | 예 | |
| segment | segment | 유저가 분류된 트래픽 그룹 이름 | instance, placement와 상호 배타적 | |
| placement | placement | 게재 위치 | instance, segment와 상호 배타적 | |
| osVersion | osVersion | OS 버전 | 최대 4개 중 하나 선택 | |
| connectionType | connectionType | 네트워크 연결 타입 | ||
| sdkVersion | sdkVersion | SDK 버전 | ||
| appVersion | appVersion | 앱 버전 | ||
| att | att | ATT 상태 | ||
| idfa | idfa | IDFA 사용 가능 여부 | ||
| abTest | abTest | A/B Test 태그 |
- 지표 필드
다음은 Reporting API가 지원하는 지표 목록입니다. 사용 가능한 지표는 분석 차원의 영향을 받으므로 실제로 수신되는 지표는 아래 표보다 적을 수 있습니다:
| 필드 이름 | 설명 |
|---|---|
| revenue | 총수익 |
| eCPM | eCPM |
| appFillRate | 광고 채움률(노출 수 / 요청 수) |
| appRequests | 광고 요청 수 |
| impressions | 노출 수 |
| completions | 완료 수
|
| revenuePerCompletion | 평균 완료 수익(수익 / 완료 수) |
| appFills | 광고 채움 수 |
| useRate | 광고 노출 대비 채움 비율 |
| activeUsers | DAU |
| engagedUsers | 광고 참여 유저 수 |
| engagedUsersRate | 광고 참여 유저 비율 |
| impressionsPerEngagedUser | 광고 참여 유저의 평균 광고 노출 수 |
| revenuePerActiveUser | 즉 ARPU 값(단위: 센트) |
| revenuePerEngagedUser | 광고 참여 유저 ARPU 값(단위: 센트) |
| clicks | 총클릭 수 |
| clickThroughRate | 클릭률(CTR) |
| completionRate | 특정 행동을 완료한 비율, 즉 전환율 |
| adSourceChecks | 광고 소스가 광고 사용 가능 여부를 확인한 횟수 |
| adSourceResponses | 광고 소스가 응답한 횟수 |
| adSourceAvailabilityRate | 광고 사용 가능 비율(노출 수 / 광고 응답 수) |
| sessions | Session 수 |
| engagedSessions | 광고 참여가 있었던 Session 수 |
| impressionsPerSession | Session당 평균 노출 수 |
| impressionPerEngagedSessions | 광고 참여가 있었던 Session당 평균 노출 수 |
| sessionsPerActiveUser | 유저당 평균 Session 수 |
4.3 인터페이스 파라미터
- 시간:
- 일 단위, UTC 시간대의 데이터를 수집합니다
- 앱:
- 수집할 앱을 지정할 수 있습니다(Android와 iOS는 별도)
4.4 데이터 저장 규칙
기본적으로 수집한 데이터는 이벤트 형태로 AE 프로젝트에 기록됩니다:
- Reporting API는 집계 데이터이므로 고정값을 유저 식별자로 사용합니다. 모든 데이터가 하나의 가상 유저에 연결되어 있다고 보면 됩니다
- 데이터의 date 필드, 즉 데이터 시간을 이벤트의 #event_time으로 사용합니다
- 데이터 이벤트 이름은 ironsource_reporting_level입니다
- 나머지 필드는 모두 저장됩니다
4.5 데이터 연동 설정 정보 템플릿
위 문서를 읽은 후 다음 정보 템플릿을 작성하여 ThinkingAI의 고객 성공 매니저에게 보내는 것을 권장합니다:
데이터 인터페이스: ironSource Reporting API
--------
회사 이름: XXX
AE 프로젝트 환경: (SAAS/프라이빗 배포)
AE 프로젝트 이름: XXX
AE 프로젝트 APP ID: XXX
데이터 수신 주소 push_url: XXX
---------
secretkey: XXX
refreshToken: XXX
---------
데이터 수집 설정
분석 세분화: xxx, xxx(입력하지 않으면 기본값 사용)
수집할 앱 Key: xxx, xxx(기본값은 전체 수집)
과거 데이터 수집 기간: yyyy/mm/dd - yyyy/mm/dd
정기 수집: 매일 X시에 전날 데이터 수집
5. 데이터 검증
AE 시스템 백엔드의 데이터 관리 - 이벤트 관리 페이지 또는 SQL IDE 페이지에서 다음 이벤트가 저장되었는지 검색할 수 있습니다:
-
클라이언트 SDK 대응 이벤트
- ta_ironSource_callback(방안 1)
- ironSource_sdk_postbacks(방안 2)
-
Impression Level Revenue API 대응 이벤트
- ironsource_ad_revenue_impression_level
-
Reporting API 대응 이벤트
- ironsource_reporting_level
6. FAQ
6.1 클라이언트 SDK 전송과 Impression Level Revenue API 전송 데이터는 어떻게 다릅니까?
- 클라이언트 SDK로 전송한 데이터는 적시성이 높지만 정확도가 낮습니다
- Impression Level Revenue API 데이터는 하루 지연되며 셋째 날이 되어야 안정되므로 적시성은 낮지만, 안정된 후의 정확도는 높습니다.
6.2 AE에 저장된 데이터와 ironSource 백엔드 UI의 데이터에 약간의 차이가 있는 이유는 무엇입니까?
- ironSource는 UTC 시간대의 수집만 제공하므로 AE 백엔드에 설정한 시간대가 UTC인지 확인하십시오
- 데이터의 약간의 차이는 ironSource API의 데이터 채널과 ironSource 백엔드 UI의 데이터 채널이 조금 다르기 때문일 수 있습니다. 예를 들어 UI의 데이터 채널은 데이터베이스 A-B에 프런트엔드 코드의 소수점 반올림 로직이 더해지고, API의 데이터 채널은 데이터베이스 A-C입니다.