ironSource Impression Level Revenue API
서드파티 데이터 통합으로 생성된 데이터는 클러스터의 소비 데이터양에 포함됩니다
개요
인터페이스 소개
| 인터페이스명 | 타입 | 세분화 | 어트리뷰션 | 비용 | 수익 | 노출 | 클릭 | 전환 |
|---|---|---|---|---|---|---|---|---|
| Impression Level Revenue API | API | 유저 데이터 | ✅ | ✅ |
Impression Level Revenue API는 유저 단위의 광고 노출 데이터를 제공하며, 이 데이터로 유저별 수익과 유저별 광고 노출 현황을 분석할 수 있습니다.
통합 절차
- ironSource SDK에 AE SDK의 유저 식별 필드를 설정합니다
- ironSource 백엔드에 로그인하여 App Key, Secret Key, Refresh Token을 가져옵니다
- AE 백엔드에 로그인하여 서드파티 통합 모듈로 이동한 후 ironSource Impression Level Revenue API 통합 계획을 추가하고 관련 설정을 완료합니다
- AE 시스템이 데이터를 정상적으로 수신했는지 확인하고 리포트를 구축합니다
1. 클라이언트 SDK 설정
ironSource 유저 데이터를 AE 프로젝트와 연결하려면 ironSource의 setUserId() 메서드로 AE의 게스트 ID를 ironSource의 UserId로 설정해야 합니다:
1.1 방안 1(자동 통합)
-
Android, iOS SDK를 연동한 경우
- SDK 버전이 2.8.0~2.8.1이면 이 방안을 바로 사용할 수 있습니다
- SDK 버전이 2.8.2 이상이면 서드파티 데이터 플러그인도 설치해야 합니다. 자세한 내용은 Android SDK 서드파티 데이터와 iOS SDK 서드파티 데이터를 참고하십시오
-
Unity SDK 버전 2.4.0 이상, Unreal SDK 버전 1.5.0 이상을 연동한 경우 이 방안을 바로 사용할 수 있습니다
AE SDK 초기화는 ironSource SDK 초기화 전에 완료해야 하며, ironSource SDK 초기화 직후에 자동 통합 코드를 활성화해야 한다는 점에 유의하십시오. 다음 단계에 따라 진행하십시오:
1. AE SDK를 초기화합니다.
2. ironSource SDK를 초기화합니다
3. `enableThirdPartySharing`을 호출하여 게스트 ID를 자동으로 설정합니다.
다음은 각 플랫폼 SDK의 코드 예시입니다:
- Android
- iOS
- Unity
- Unreal
// 1. Android SDK 초기화
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. ironSource SDK 초기화
// ...
// 3. enableThirdPartySharing 인터페이스를 호출하여 ta_distinct_id를 ironSource 이벤트에 설정
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.IRON_SOURCE);
// 1. iOS SDK 초기화
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
config.mode = TDModeDebug;
[TDAnalytics startAnalyticsWithConfig:config];
// 2. ironSource SDK 초기화
// ...
// 3. enableThirdPartySharing 인터페이스를 호출하여 ta_distinct_id를 ironSource 이벤트에 설정
[TDAnalytics enableThirdPartySharing:TDThirdPartyTypeIronSource];
// 1. Unity SDK 초기화
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2. ironSource SDK 초기화
// ...
//3. enableThirdPartySharing 인터페이스를 호출하여 ta_distinct_id를 ironSource 이벤트에 설정
TDAnalytics.EnableThirdPartySharing(TDThirdPartyType.IRONSOURCE);
// 1. Unreal SDK 초기화
UTDAnalytics::Initialize();
// 2. ironSource SDK 초기화
// ...
// 3. enableThirdPartySharing을 호출하여 ta_distinct_id를 ironSource 이벤트에 설정
TArray<FString> EventTypeList;
EventTypeList.Emplace(TEXT("TAThirdPartyShareTypeIRONSOURCE"));
UTDAnalytics::EnableThirdPartySharing(EventTypeList, AppID);
1.2 방안 2(수동 통합)
수동 통합 방안에서는 ironSource SDK에서 setUserId() 인터페이스로 AE 프로젝트의 게스트 ID를 설정해야 합니다.
AE SDK 초기화는 반드시 ironSource SDK 초기화 전에 완료해야 하고, setUserId 인터페이스는 반드시 ironSource SDK 초기화 후에 호출해야 한다는 점에 유의하십시오. 다음 단계에 따라 진행하십시오:
1. AE SDK를 초기화합니다.
2. ironSource SDK를 초기화합니다.
3. `setUserId`를 호출하여 게스트 ID를 설정합니다.
다음은 각 플랫폼 SDK의 수동 통합 코드 예시입니다:
- Android
- iOS
- Unity
// 1. Android SDK 초기화
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. ironSource SDK 초기화
// ...
// 3. AE의 게스트 ID 가져오기, AE의 #distinct_id에 대응
String distinctId = TDAnalytics.getDistinctId();
// 4. AE의 게스트 ID를 ironSource의 User ID로 설정
IronSource.setUserId(distinctId);
// 1. iOS SDK 초기화
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
config.mode = TDModeDebug;
[TDAnalytics startAnalyticsWithConfig:config];
// 2. ironSource SDK 초기화
// ...
// 3. AE의 게스트 ID 가져오기, AE의 #distinct_id에 대응
NSString *distinctId = [TDAnalytics getDistinctId];
// 4. 게스트 ID를 ironSource 수집 이벤트에 설정
[IronSource setUserId:distinctId];
// 1. Unity SDK 초기화
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2. ironSource SDK 초기화
// ...
// 3. AE의 게스트 ID 가져오기, AE의 #distinct_id에 대응
var distinctId = TDAnalytics.GetDistinctId();
// 4. 게스트 ID를 ironSource 수집 이벤트에 설정
IronSource.Agent.setUserId(distinctId);
2. 인증 정보 가져오기
다음으로 ironSource 백엔드에 로그인하여 필요한 인증 정보를 가져와야 합니다
- 먼저 오른쪽 상단의 사용자 메뉴를 클릭하여 My Account 페이지의 Reporting API 탭으로 이동한 후 Secret Key와 Refresh Token을 가져옵니다
- 다음으로 ironSource 백엔드의 Ad Unit 페이지로 이동하여 APPLICATIONS 목록에서 연동할 앱을 선택하면 오른쪽 카드에 해당 앱의 App Key가 표시되므로 이를 기록해 둡니다(iOS와 Android는 별개이므로 두 플랫폼의 데이터를 모두 연동하려면 계획 두 개를 설정하고 각각의 App Key를 입력해야 합니다)
3. 계획 설정
SDK 설정을 완료한 후 AE 시스템 백엔드에 로그인하여 서드파티 통합 모듈에서 ironSource Impression Level Revenue API 설정을 완료해야 합니다. 아래 그림은 ironSource의 설정 화면입니다:
3.1 인증 정보 설정
인증 정보 아래의 인증 정보 설정 버튼을 클릭하고 팝업 창에 인증 작업에서 가져온 정보를 입력합니다(Refresh Token은 먼저 편집 아이콘을 클릭해야 입력란이 나타납니다)
3.2 동기화
동기화 모듈에서 AE 시스템이 ironSource Impression Level Revenue API 데이터를 정기적으로 수집하는 정책을 설정할 수 있으며, 매일 특정 시각 또는 매시간 일정 기간의 데이터를 수집하도록 선택할 수 있습니다. 수집한 데이터도 데이터양에 포함되므로 너무 긴 기간의 데이터를 정기적으로 수집하지 않는 것을 권장합니다
3.3 유저 식별 필드
ironSource Impression Level Revenue API는 유저 수준 데이터를 제공하므로 유저 식별 규칙을 설정해야 합니다. AE 시스템은 이 설정에 따라 수집한 데이터를 변환할 때 해당 필드를 데이터의 유저 식별 필드로 설정합니다.
이 문서에 따라 클라이언트 SDK를 설정한 경우 다음 설정을 사용하십시오:
- 계정 ID 연관 필드: 없음
- 게스트 ID 연관 필드: user_id
3.4 이벤트 테이블 저장 설정
이벤트 테이블 저장 설정 스위치를 켜면 콜백 데이터가 모두 이벤트 테이블에 기록됩니다. 이벤트 데이터 저장을 활성화할 것을 권장합니다.
3.5 유저 속성 저장 규칙
기본적으로 AE 시스템은 ironSource Impression Level Revenue API 데이터를 유저 속성에 기록하지 않습니다. 일부 필드를 유저 테이블에 기록하려면 먼저 규칙을 켜서 실행되도록 한 후 속성 매핑 기능으로 유저 테이블에 기록할 필드를 추가하십시오. 소스 속성명에는 필드의 저장 필드명을 입력해야 합니다:
3.6 통합 설정
통합 설정 모듈에서 데이터 수집의 세부 설정을 제어할 수 있습니다. 예를 들어 저장 후 이벤트 이름 등을 설정할 수 있습니다.
통합 설정은 JSON이며, 필요에 따라 내용을 조정할 수 있습니다
| 모듈 | 이름 | 의미 |
|---|---|---|
| sink_event | event_name | 저장 후 이벤트 이름, 커스텀 가능 |
| transfer | double_columns | 숫자 타입으로 변환되는 지표 필드. 그 밖의 저장 필드는 모두 문자열 타입으로 저장되며, 조정하지 않는 것을 권장합니다 |
3.7 데이터 저장 규칙
- 데이터의 user_id를 데이터의 게스트 ID로 사용합니다. 이 필드는 AE 프로젝트의 게스트 ID와 대응해야 합니다
- 데이터의 event_timestamp 필드, 즉 광고 노출 시간을 이벤트의 #event_time으로 사용합니다
- 데이터 이벤트 이름은 ironsource_ad_revenue_impression_level입니다
- 나머지 필드는 모두 저장됩니다. 다음은 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, 즉 "1. 클라이언트 SDK 설정"에서 설정한 유저 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 |
- 지표 필드
| 필드 이름 | 설명 | 값 예시 |
|---|---|---|
| revenue | 수익 금액 | 0.5 |
3.8 표준화 필드
다음 이벤트 속성은 표준화 처리됩니다:
| 원본 필드 | 표준화 필드 | 의미 |
|---|---|---|
| ad_network | te_ads_object.media_source | 수익화 채널 |
| ad_unit | te_ads_object.ad_group_name | 수익화 광고 Unit 이름 |
| placement | te_ads_object.placement | 수익화 광고 위치 |
| app_name | te_ads_object.app_name | 앱 이름 |
| country | te_ads_object.country | 국가/지역 코드 |
| platform | te_ads_object.platform | 플랫폼(Android, iOS 등) |
| USD 고정값 | te_ads_object.currency | 수익화 수익의 통화 |
| revenue | te_ads_object.revenue | 수익화 수익 |