기본 SDK 연동 가이드

요약: 모바일 또는 CTV 앱 개발자와 함께 SDK를 안드로이드 또는 iOS 앱에 연동 및 인스톨합니다. 기본 연동 태스크가 완료되면 앱은 어트리뷰션 인스톨 및 인앱 이벤트 측정을 위해 준비됩니다.   

 관련 자료

앱과의 SDK 연동 계획을 완전히 이해하려면 다음 문서를 읽어보십시오.

dev key 확인

개발자가 SDK를 인스톨하고 연동하려면 먼저 dev키를 검색해야 합니다. 앱스플라이어는 dev key를 사용하여 계정을 고유하게 식별합니다. Dev key는 SDK가 계정에 속한 데이터를 안전하게 송수신하도록 만드는 필수 값입니다.

Dev key를 확인하려면:

  1. 앱스플라이어에서 설정 < 앱 설정 메뉴로 갑니다
  2. dev key를 복사하여 모바일 개발사에 보냅니다.

    af_devkey.png

  3. 모바일 개발사에 인스톨SDK 연동하기에 대한 지침을 제공합니다.

어트리뷰션

SDK는 어트리뷰션 목적으로 식별자를 수집합니다. 인스톨이 올바르게 기록되고 어트리뷰트되도록 하기 위해 다음 가이드라인을 검토하고 따르십시오. 

모든 플랫폼

인스톨을 위한 고유 식별자

앱스플라이어 ID는 새 앱을 인스톨할 때마다 자동으로 생성됩니다. 마케터는 아무런 액션도 필요하지 않습니다.

이 식별자를 사용하여 다음 액션을 수행할 수 있습니다.

BI 시스템의 고유 식별자를 앱스플라이어와 연동하기

앱스플라이어 SDK에서 고객 사용자 ID(CUID)를 설정해두면, BI 시스템의 고유 ID가 앱스플라이어 ID 및 기타 식별자 값과 상호 참조할 수 있습니다. CUID는 앱스플라이어 로데이터 리포트에서 이용할 수 있습니다. 또한, 포스트백 API에서 해당 ID를 확보하여 귀사 내부 ID와 상호 참조할 수 있습니다. 

CUID 구현을 위한 개발자 지침을 참조하십시오.

Android만 해당

다음 섹션에서는 구글 플레이 스토어 또는 써드 파티 앱 스토어의 어트리뷰션 고려 사항을 설명합니다.

구글 플레이에 게시된 앱을 어트리뷰트하기 

구글 플레이 인스톨 리퍼러

구글 플레이 인스톨 리퍼러 API어트리뷰션 정확도를 개선하고 인스톨 사기로부터 보호를 제공하며 구글 플레이에서 참조 데이터를 안전하게 검색할 수 있게 합니다(예를 들어, 앱이 처음 설치된 시점의 앱 버전). 

개발자에게 구글 플레이 인스톨 리퍼러 API를 추가하기 위한 지침을 제공하는 것이 좋습니다. 

GAID

SDK V4.8.0부터는 앱스플라이어가 이 기기 식별자를 자동으로 수집합니다.

타사 앱 스토어로 앱 어트리뷰트하기

앱스플라이어를 사용하면 Amazon, Opera, GetJar, Baidu 및 Huawei와 같은 써드파티 앱 스토어로부터의 인스톨을 어트리뷰트할 수 있습니다.이를 통해 구글 플레이 스토어를 사용할 수 없는 시장에서도 앱을 홍보하고 더 많은 잠재 고객에게 도달할 수 있습니다.

앱스플라이어는 타사 앱 스토어의 맥락에서 다음과 같은 어트리뷰션을 지원합니다.

  • IMEI 또는 안드로이드 ID: SDK는 IMEI 또는 안드로이드 ID를 자동으로 수집하지 않습니다. 그러나 이러한 식별자를 수집해야 할 필요가 있는 경우(예: 중국 국내 시장의 앱) 개발자는 다음 수집 유형 중 하나를 구현할 수 있습니다.
    • 수동 수집: 앱은 ( setImeiData 또는 setAndroidIdData API를 사용하여) IMEI 또는 안드로이드 ID를 SDK로 전달합니다. SDK는 데이터를 앱스플라이어 서버로 전송합니다. 
    • 기기 ID 수집에 대한 옵트인: SDK가 IMEI 또는 안드로이드 ID를 수집하도록 강제합니다. 
  • OAID: 써트 파티 안드로이드 앱 스토어의 인스톨을 어트리뷰트합니다. 자세한 내용은 OAID 구현 가이드를 참조하십시오.
  • 인스톨 리퍼러: SDK는 Samsung Gallery 및 Huawei AppGallery의 리퍼럴 데이터에 대한 검색을 지원합니다.

iOS만 해당

다음 세션에는 iOS 14+ 기기 지원에 대한 중요한 정보가 포함되어 있습니다.

앱 추적 투명성(ATT, App Tracking Transparency) 지원 설정하기

배경

iOS 14.5부터, IDFA를 수집하려면 사용자의 동의가 필요합니다. 이는 실제로 IDFA 액세스를 앱 추적 투명성(ATT) 프레임워크가 통제한다는 의미입니다. 기기가 iOS 14 이상일 경우, SDK는 ATT 프레임워크를 사용하여 기기 IDFA 액세스 권한을 얻습니다. 

ATT에 대한 소개는 ATT 원칙을 참조하십시오.

IDFA를 이용하여 어트리뷰션을 할 경우, IDFA는 앱 최초 실행 시점에 전송되어야 합니다. 이를 위해, 앱스플라이어 SDK는 waitForATTUserAuthorization 유틸리티를 제공합니다. 

waitForATTUserAuthorization overview

 중요!

ATT 대화상자를 호출하지 않으려면, waitForATTUserAuthorization을 호출하지 마십시오.

waitForATTUserAuthorization을 통해 데이터를 앱스플라이어 서버로 보내기 전에 SDK가 ATT 상태를 지연하고 대기하는 기간을 구성할 수 있습니다.

ATT-flowchart_en-us.png

사용자가 앱을 실행하는 시점에는 ATT 상태가 결정되지 않습니다. waitForATTUserAuthorization 시간 초과 기간에 SDK는 앱 실행 이벤트와 연속적인 인앱 이벤트 인메모리(in-memory)를 오프라인 이벤트가 기록되는 방식과 유사하게 순차적으로 기록합니다.

  • 사용자가 ATT 프롬프트(IDFA 컬렉션)에 동의하는 경우:
    • SDK가 IDFA를 임시 저장된(cached) 이벤트에 추가합니다.
    • SDK가 (타임아웃을 기다리지 않고) 바로 구동되어 임시 저장된 이벤트를 IDFA와 함께 전송합니다.
  • 사용자가 ATT 메시지를 거부하는 경우: SDK가 (타임아웃을 기다리지 않고) 바로 구동되어 임시 저장된 이벤트를 IDFA 없이 전송합니다.
  • 타임아웃이 종료되고 ATT 상태가 notDetermined로 남아 있는 경우: IDFA가 없이 SDK가 시작되고 캐시한 이벤트를 발송합니다.

고려 사항 

  • waitForATTUserAuthorization을 설정하지 않고 requestTrackingAuthorization을 호출하면 iOS 14 이상의 기기에 대한 IDFA 없이 실행 및 이벤트가 전송됩니다.
  • 사용자가 타임아웃 중간에 앱을 백그라운드로 이동시키면,
    • 앱이 휴대폰 화면(foreground)에 표시될 때까지 타이머가 일시 중지됩니다.
    • 이벤트는 인-메모리에 캐시됩니다.
  • 사용자가 앱을 종료하면 제한 시간 동안 종료됩니다.
    • 다음 앱 실행 시점에 타이머가 재시작합니다.
    • 캐시 이벤트가 손실됩니다.

ATT 동의 대화상자 사용자정의하기

ATT 메시지를 사용자정의할 수 있습니다. 요청의 목적을 명확히 설명하는 메시지는 사용자의 선택 비율을 높이는 데 도움이 될 수 있습니다.

메시지를 작성할 때 다음 사항을 고려하십시오.

메시지가 완료되면 개발자에게 텍스트와 구현 지침을 제공합니다.

ATT 메시지의 일부 외부 예시를 참조하십시오.

SKAN 어트리뷰션 지원

 참고

SKAN 어트리뷰션을 지원하려면 iOS SDK V6.2.3 이상으로 업그레이드하십시오.

SKAN은 iOS가 사용하는 클래스로, 앱 설치가 광고에 기인해서 발생했는지 검증합니다. 이 앱 설치 유효성 검증 프로세스에는 소스 앱과 광고 대상 앱이 있습니다. 

소스 앱은 광고 네트워크의 광고를 자신의 지면에 게재하여 광고 캠페인에 참여하는 앱입니다. 광고를 게재하도록 앱을 구성하는 작업은 앱스플라이어 SDK 범위 내에 없습니다. 광고 게재를 위한 작업은Apple 가이드를 따르십시오.

(앱스플라이어 SDK가 설치된) 광고주 앱에 대해서, 앱스플라이어의 SKAN 솔루션은 SKAN을 이용하여 어트리뷰션 포스트백을 제공하며 앱스플라이어는 데이터를 수집, 해석, 집약하고 동시에 개인정보를 보호합니다. 앱이 설치된 후 처음 실행되면, 앱스플라이어 플랫폼은 앱 광고주(마케터)가 설정한 상태에 따라 SDK에 SKAN 전환 값을 설정하는 방식을 지시합니다.

SKAN 솔루션 사용 방법:

  • 마케터는 앱스플라이어에서 SKAN 측정을 설정해야 합니다. 개발자는 어떠한 작업도 수행할 필요가 없습니다.
  • 앱스플라이어 SDK는 자동으로 필요한 SKAN API를 호출합니다.
  • 앱스플라이어에 의존하여 SKAN 어트리뷰션을 사용할 때 다른 SDK에서 SKAN 호출을 사용하지 않도록 설정해야 합니다.
  •  App Store에서 개발자나 마케터가 해야 할 작업이나 등록 절차는 없습니다. 

SKAN 어트리뷰션을 비활성화하려면 개발사에 SDK에서 비활성화하도록 지시합니다. 

인앱 이벤트 기록하기

인앱 이벤트(In-app event, IAE)는 앱에서 어떤 일이 일어나는지 정보를 제공합니다. 인앱 이벤트를 기록하면 ROI(투자 수익)나 LTV(생애 가치)와 같은 KPI들을 측정할 수 있습니다. 시간을 두고 기록할 이벤트를 정의할 것을 권고합니다.

측정할 인앱 이벤트를 결정했으면 구현 지침에 대한 링크를 포함하여 이벤트 이름과 이벤트 파라미터를 개발사에 전송합니다. 

인앱 이벤트에 대한 자세한 내용은 리치 인앱 이벤트 가이드를 참조하십시오.

모든 플랫폼

수익 기록

어떤 인앱 이벤트로도 수익 값을 보낼 수 있습니다. 수익을 포함하려면 af_revenue 파라미터를 사용해야 합니다. 앱스플라이어가 대시보드와 로데이터 리포트에서 실제 수익으로 계산하는 유일한 이벤트 파라미터입니다. 더 알아보기.

개발사 지침은 수익 기록을 참조하십시오.

인앱 구매 유효성 검증

앱스플라이어의 SDK는 인앱 구매에 대해서 서버 확인 기능을 제공합니다. 구매 검증을 통과하면 앱스플라이어로 인앱 구매 이벤트가 자동 전송됩니다. 그러므로 이 이벤트를 따로 직접 전송하면 인앱 구매 내역이 중복되어 기록됩니다.

업계 수직 구조

예를 들어, 여행, 게임 또는 전자상거래와 같은 수직별 권장되는 앱 이벤트 목록을 참조하십시오.

원링크로 딥링킹하기

원링크는 멀티 플랫폼 어트리뷰션과 유저를 앱 내 특정 콘텐츠로 보내는 딥링킹(deep linking)을 지원하는 앱스플라이어 솔루션입니다.

모든 플랫폼

기기 감지 및 리다이렉션

앱을 설치하지 않은 사용자의 경우 원링크는 장치 유형을 검색하여 올바른 대상(예를 들어, Google Play, Apple App Store, 타사 앱 스토어 또는 웹 페이지)으로 리디렉션합니다. 이것은 원링크 템플릿 설정에 기반합니다. 더 알아보기

딥링킹

앱을 설치한 사용자에 대해 원링크는 앱을 열어줍니다. 앱을 열 뿐만 아니라 앱 내의 특정 활동이나 페이지로 사용자를 딥링킹할 수도 있습니다. 이렇게 하려면 개발사가 통합 딥링킹(UDL)을 구현해야 합니다.

일러두기:

  • UDL은 SDK V6.1 이상을 요구합니다.
  • 딥링킹에 원링크를 이미 사용하고 있는 고객은 UDL 대신 레거시 방법을 사용하고 있을 수 있습니다.

원링크로 딥링킹 설정하기 가이드에서 상세 설명을 확인하십시오.

디퍼드 딥링킹(Deferred Deep Linking)

앱을 설치하지 않은 사용자의 경우 원링크는 장치 유형을 검색하여 올바른 대상인 Google Play, Apple App Store, 타사 앱 스토어 또는 웹 페이지로 리디렉션합니다. 사용자가 앱을 실행하면 디퍼드 딥링킹을 사용하여 앱 내의 특정 활동 또는 페이지로 리디렉션할 수 있습니다.

이렇게 하려면 개발사가 통합 딥링킹(UDL)을 구현해야 합니다.

일러두기:

  • UDL은 SDK V6.1 이상을 요구합니다.
  • 디퍼드 딥링킹에 원링크를 이미 사용하고 있는 고객은 UDL 대신 레거시 방법을 사용하고 있을 수 있습니다.

원링크로 디퍼드 딥링킹 설정하기 가이드를 참조하십시오.

어트리뷰션 액세스 및 데이터 딥링킹

다음 표에서는 어트리뷰션을 검색하고 데이터를 딥링킹하는 데 사용할 수 있는 방법에 대해 설명합니다.

방법 직무별 작업? 수익 반환 검색 방법 어트리뷰션 데이터 딥링킹 데이터 사용 가능 여부
푸시 API
  • 마케터
  • 백엔드 개발사
보통 1분 이내 백엔드 Y N 프리미엄
풀 API
  • 마케터
  • 백엔드 개발사
  • 주기적{실시간 아님).
  • 로데이터 리포트 다운로드를 예약할 수 있습니다. 
백엔드 Y Y 로데이터 리포트용 프리미엄
Data Locker
  • 마케터
  • 백엔드 개발사

시간별 보고서는 1-3시간 이내에 사용 가능합니다.

다음 옵션 중 하나를 통한 클라우드 스토리지:

  • AWS의 앱스플라이어 소유 버킷
  • 사용자 소유 스토리지(AWS 또는 GCS)
Y Y 프리미엄
전환 데이터 가져오기(GCD) 
  • 마케터
  • 모바일 개발사

개발자 설명서를 참조하십시오

최대 5초  SDK Y Y 모든 계정
통합된 딥링킹(UDL)
  • 마케터
  • 모바일 개발사

개발자 설명서를 참조하십시오

최대 1초 SDK N Y 모든 계정

iOS 14.5 이상을 동의하지 않는 사용자의 경우 다음을 참고하십시오.

  • 유료 미디어 및 온드 미디어에 UDL을 사용할 경우 딥링킹 데이터를 사용할 수 있습니다.
  • 유료 미디어에 대해 GCD를 사용할 경우 데이터는 제한되며 어트리뷰트 및 딥링킹 세부 정보가 포함되지 않습니다.

 

다음을 수행할 것을 권고합니다.

  • Push API를 사용하여 어트리뷰션 데이터를 검색하고 추가 처리를 위해 서버로 보냅니다. 이 방법은 데이터를 사용할 수 있을 때까지 대기하므로 정확도가 높고 실시간에 가깝습니다. GCD는 실시간으로 데이터를 반환하지만 때로 5초 이상 후에 최종 어트리뷰션 결정이 결정될 때 부정확할 수도 있습니다.
  • 풀 API를 사용하여 실시간 어트리뷰션 데이터를 주기적으로(예를 들어, 매일) 보완하고 발생할 수 있는 통신 오류를 보완합니다.

SDK 연동을 테스트하는 것은

SDK 연동이 완료되면 앱스플라이어 대시보드로 이동하여 SDK 연동 테스트 페이지에서 오가닉 및 비오가닉 인스톨, 인앱 이벤트 및 딥링킹(리타게팅)을 테스트할 수 있습니다. 이렇게 하면 인스톨 및 인앱 이벤트가 올바르게 기록되고 어트리뷰트될 수 있습니다.

개발자가 SDK 연동을 테스트해야 하는 경우 개발자를 계정의 사용자로 추가하여 대시보드에 액세스할 수 있도록 합니다.

테스트 시나리오 및 지침은 SDK 연동 테스트를 참조하십시오.

도움이 되었습니까?