SDK 삽입

분석 시스템의 핵심 구성요소인 SDK는 앱 인스톨과 인앱 이벤트를 어트리뷰트하고 인앱 애널리틱스에 필요한 데이터 포인트를 확보하는 역할을 수행합니다. 데이터를 측정하기 위해 본 문서의 안내에 따라 Wisetracker SDK를 Android App에 연동하여 주시기 바랍니다.

1. 필수 설정

필수 설정이란 SDK가 동작하기 위해서 반드시 앱에 추가되어야 하는 최소한의 설정을 말합니다. 필수 설정을 적용하게 되면 인스톨, 세션, 단말기 정보 등을 측정할 수 있게 됩니다.

앱에 SDK 추가 (JFrog Artifactory 이용)

프로젝트의 build.gradle ( root 파일 ) 에 아래와 같이 와이즈트래커의 maven repository 주소를 추가합니다.

저장소가 JFrog에서 Github으로 변경되었습니다.

이에따라 JFrog를 이용하는 방식은 2023년 9월까지만 제공되며, 이후부터는 아래 Github Package 이용하는 방식으로 필수 변경이 필요합니다.

(기존 JFrog에서 사용되던 라이브러리와 동일한 라이브러리가 포함되어있습니다)

gradle

allprojects {
    repositories {
        google()
        mavenCentral()
        /* sdk repository url 추가 */ 
        maven { url 'https://wisetracker.jfrog.io/artifactory/wisetracker-gradle-release-local' }
    }
}

앱에 SDK 추가 (Github Package 이용)

프로젝트의 build.gradle ( root 파일 ) 에 아래와 같이 와이즈트래커의 Repository 주소를 추가합니다.

gradle

allprojects {
    repositories {
        google()
        mavenCentral()
        /* wisetracker sdk repository config */
        maven {
            def endPoint = "https://analytics.wisetracker.co.kr/console/android/sdk/github/credentials.do"
            url = uri(new URL(endPoint+'?name=URI').text)
            credentials {
                username = new URL(endPoint+'?name=USER').text
                password = new URL(endPoint+'?name=TOKEN').text
            }
        }
    }
}

gradle.kts

아래와 같은 오류 메시지가 보여지는 경우, "Gradle Scripts"의 "settings.properties"파일을 수정해야 합니다.

A problem occurred evaluating root project 'XXX'.

Build was configured to prefer settings repositories over project repositories but repository 'Google' was added by build file 'build.gradle'

Gradle "settings.gradle"

...
dependencyResolutionManagement {
  
  // =====================
  // 위와 같은 오류가 발생하면
  // 아래 한 줄을 주석처리합니다.
  // =====================
  
  // repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

  repositories {
    google()
    mavenCentral()
    ...
  }
}
*/
...

"app"모듈단위의 app/build.gradle 파일에 있는 dependencies에 아래와 같이 Wisetracker SDK를 추가해주세요.

gradle

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    ....
    // SDK
    implementation "com.sdk.wisetracker:base_module:latest.release"
    implementation "com.sdk.wisetracker:new_dot_module:latest.release"
}

gradle.kts

AuthorizationKey 등록

프로젝트의 app/res/values/strings.xml 파일에 아래 코드를 추가합니다.

XML

<string-array name="dotAuthorizationKey">
    <item name="useMode">1</item>
    <item name="serviceNumber">xxxxx</item>    /* 서비스 번호 필수 변경! */
    <item name="expireDate">14</item>
    <item name="isDebug">false</item>
    <item name="isInstallRetention">true</item>
    <item name="isFingerPrint">true</item>
    <item name="accessToken"></item>
</string-array>

추가한 코드 중 serviceNumber의 value를 올바른 값으로 변경해야 합니다.

와이즈트래커 대시보드에 로그인하여 설정 > 서비스설정 메뉴에서 '서비스번호' 항목에 기재된 숫자를 확인 후 복사하여 serviceNumber 값을 변경 해 주세요.

서비스번호 확인

HTTP 통신 허용

프로젝트의 Target API가 API Level 28 이상일 경우에 적용하는 설정입니다. 아래와 같이 HTTP 통신을 허용하는 두 가지 설정을 추가해주세요.

AndroidManifest.xml 설정

XML

<!-- AndroidManifest.xml -->
<application
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:networkSecurityConfig="@xml/network_security_config"  /* 추가 */
    android:theme="@style/AppTheme">

app/res/xml/network_security_config.xml 설정

• 이 파일이 없으면 해당 위치에 새로 만들어주세요.

XML

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">trk.analytics.wisetracker.co.kr</domain>
    </domain-config>
</network-security-config>

프로가드(Proguard) 설정

프로젝트에 프로가드가 설정되어 있는 경우, 와이즈트래커(Wisetracker) SDK 관련 예외 설정이 필요합니다. 프로가드 설정 파일 하단에 아래와 같이 코드를 추가해주세요.

# app/proguard-rules.pro

# --- wisetracker 이름/코드 모두 보존(난독화/축소 제외) ---
-keepattributes *Annotation*,InnerClasses,EnclosingMethod,Signature
-keep class com.google.gson.** { *; }
-keep class com.sdk.wisetracker.** { *; }

초기화

Application을 상속받는 클래스가 아닌 Activity를 상속받는 기본 화면의 onCreate() 함수에 적용해 주세요. 여기서 말하는 기본 화면은 AndroidManifest.xml 파일에 선언된 Activity 중, "android.intent.action.MAIN" 와 "android.intent.category.LAUNCHER" Intent-Filter 가 적용된 Activity를 의미합니다.

Java

import com.sdk.wisetracker.new_dot.open.DOT;
import com.sdk.wisetracker.base.tracker.data.init.InitializeManager;

public class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) { 
        // SDK 초기화.
        if (!InitializeManager.initComplete) {
            DOT.initialization(this);
        }
        else if (getIntent() != null){
            DOT.setDeepLink(getApplicationContext(), getIntent());
        }
    }
}

Kotlin

어트리뷰션 데이터 접근

DOT.getAttributedInfo 호출을 통해 와이즈트래커 대시보드에서 생성한 어트리뷰션링크를 통해 앱을 설치한 유저(non-organic)의 attribute 정보를 확인할 수 있습니다.

✅ 필수 체크 사항

1

Android SDK 최신버전이 적용되어야 합니다.

2

Android API 가 26 이상 환경에서 동작합니다.

3

SDK 초기화 함수 DOT.initialization(this)호출한 이후 사용해야 합니다.

MainActivity(Kotlin) 예제 코드

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (!InitializeManager.initComplete) {
           // SDK 호출
            DOT.initialization(this);
            
            // attribute 정보를 추출
            DOT.getAttributedInfo(new DOT.AttributedInfoCallback() {
                @Override
                public void doTask(Map<String, Object> result) {
                    WiseLog.d("current attribution data on main activity ( onCreate ) : " + result.toString());
                    // result 파라미터를 필요에 따라 사용합니다.
                }
            });
        }
        else if (getIntent() != null){
            DOT.setDeepLink(getApplicationContext(), getIntent());
        }
    }
}

result 파라미터의 형태는 아래의 예시를 참고 해주세요.

(result 파라미터 데이터가 비어있다면 Organic 으로 식별된 결과입니다.)

① 앱설치(예시)

{
  install_media="P1540365166967",      >> 광고채널    
  install_mediaNm="WISE_TEST1",        >> 광고채널명 
  install_campaign="C1710215861051",   >> 광고캠페인  
  install_campaignNm="WISETRACKER",    >> 광고캠페인명
  install_medium="",                   >> 광고타입
  install_keyword=""                   >> 광고키워드   
}

② 앱실행(예시)

{
  open_media="P1540365166967",
  open_mediaNm="WISE_TEST1",
  open_campaign="C1710215861051",
  open_campaignNm="WISETRACKER",
  open_medium="",
  open_keyword=""
}

이벤트 설정

✅화면전환 또는 이벤트 분석을 위한 적용 방법은 플러그인 설정 및 초기화 이후에 아래 링크를 클릭하거나, 좌측 IN-APP EVENT 메뉴를 통해 가이드를 확인하실 수 있습니다.

👉페이지 분석 가이드로 이동하기

👉인앱 이벤트 설정으로 이동하기

Hybrid App을 위한 설정 추가

Hybrid App인 경우에만 적용하면 되는 설정으로, WebView로 표시한 웹페이지 내에서 발생하는 이벤트를 측정하기 위해 필요합니다. 웹뷰로 불러온 페이지를 감지할 수 있도록 다음과 같이 setWebView 함수를 호출해주세요.

Java

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    
    WebView webView = findViewById(R.id.web_view);
    ...
    // SDK 호출
    DOT.setWebView(webView);
}

Kotlin

그리고 WebViewClient 의 각각의 콜백에 아래와 같이 적용해주세요.

Java

webView.setWebViewClient(new WebViewClient() {
    @Override
    public void onPageStarted(WebView view, String url, Bitmap favicon) {
        // 1. document 에 DOT 객체 주입.
        WiseLog.d("onPageStarted" + url );
        DOT.injectSdkToHtmlDocument(view,true);
        super.onPageStarted(view,url,favicon);
    } 

    @Override
    public void onPageFinished(WebView view, String url) {
        WiseLog.d("onPageFinished" + url );
        DOT.injectJavascriptWithDomSearch(view,url,true);
        super.onPageFinished(view, url);
    }
});

Kotlin

2. 고급 설정

고급 설정이란 반드시 적용할 필요는 없지만 와이즈트래커의 확장된 분석기능을 활용하기 위해 추가해야 하는 설정을 말합니다. 필요에 따라 선택적으로 설정을 추가해주시기 바랍니다.

App Link 설정

앱 링크 설정 가이드는 별도의 문서에 정리되어 있습니다.

App Link 설정

딥링크 설정

딥링크가 설정된 url 을 통해서 오픈된 이벤트를 분석합니다. AndroidManifest.xml 파일에서 앱의 환경에 맞춰 딥링크로 오픈되는 Activity의 android:host, android:scheme 값을 설정해 주세요.

✔️와이즈트래커 대시보드에서 생성한 어트리뷰션링크를 통해 테스트 및 광고집행을 진행하며, 딥링크 클릭 시 와이즈트래커 서버가 앱의 설치 여부를 판단하여 동작합니다. 다음과 같은 형태의 "https://xxxx.page.link" 링크를 클릭하게 되면 해당 URL이 가르키는 웹으로 이동함으로써 와이즈트래커가 수집하여야 하는 광고파라미터값이 유실될 수 있어, 앱으로 바로 이동 가능한 다음과 같은 형태의 Unique 한 커스텀스키마가 필요합니다.

이미 만들어진 유니버셜링크가 존재 한다면 와이즈트래커에서 사용할 딥링크 진입 스키마 설정을 '추가' 해 주세요. (딥링크스키마 설정 추가시 다른 링크에 어떠한 영향도 주지 않습니다.)

XML

<!-- 예시는 wisetracker://wisetracker.co.kr 링크로 앱 진입 경우 -->
<activity android:name="com.sample.DeepLinkActivity"
          android:launchMode="singleTop" >
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- 딥링크로 진입될 스키마와 호스트 정보 수정 -->
        <data android:host="wisetracker.co.kr"
              android:scheme="wisetracker" />
    </intent-filter>
</activity>

위의 샘플 코드와 같이 AndroidManifest.xml에 설정을 마치시게 되시면 다음과 같은 형태의 커스텀 스키마가 설정된 상태가 됩니다.

wisetracker://wisetracker.co.kr

여기서 wisetracker:// 부분이Scheme(혹은 프로토콜) 입니다. 개발자가 앱에 이 Scheme를 쓸 것이라고 결정하는 것이며, 해당 Scheme만 설정을 하셔도 됩니다. 이어서 wisetracker.co.kr 부분은 특정 페이지에 도달하도록 만들기 위한 host(혹은 path or 도메인) 입니다.

딥링크 분석

딥링크로 실행되는 Activity의 onCreate와 onNewIntent에 아래와 같이 setDeepLink를 추가합니다.

Java

public class DeepLinkActivity extends Activity {
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        /* 중략.. */
        if (!InitializeManager.initComplete) {
            DOT.initialization(this);
        }
        else if (getIntent() != null){
            DOT.setDeepLink(getApplicationContext(), getIntent());
        }
    }
    
    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        DOT.setDeepLink(getApplicationContext(), getIntent());
    }
}

kotlin

딥링크 예외 처리

와이즈트래커 SDK를 적용하고, 광고 분석을 하고자 하는 경우, 와이즈트래커 시스템에서 발급된 광고 분석 링크에 의해서 앱을 실행하는 딥링크 URL에 다음과 같이 광고 분석 목적의 파라미터가 추가될 수 있습니다.

특히 웹앱의 경우 url 이라는 파라미터를 사용하여 웹뷰에 로딩되어질 웹페이지 url을 전달하는 경우가 많은데, 이와 관련하여 아래의 케이스에도 문제가 없는지 반드시 확인하시기 바랍니다.

// 기존의 deeplink 에 광고 분석 파라미터가 추가된 예시를 보여주고 있습니다. 
YOUR_SCHEMA://YOUR_HOST?url={YOUR_WEB_PAGE_URL}&trackId=M00200881641977334670
&w_start=h&_wtno=102&_wts=P1641977288745
... 중간 생략 ...
&w_end=h

8MB

SDK데이터검증 가이드북.pdf

PDF

Open

딥링크 설정 후 테스트시 가이드북을 참고해 주세요.

Deffered Deep Link (지연된 딥링크) 적용

1. 지연된 딥링크 기능은 Growth 레벨 이상의 사용자에게 제공됩니다.

2. 지연된 딥링크 기능 제공 SDK 버전 - Android SDK: Base Modeul - 1.0.81 이상 / New Dot Module - 1.0.51 이상 - iOS SDK: RW 1.1.52 이상

기존의 DOT.initialization SDK 초기화 함수 대신 아래의 DOT.initializationForDeferredCallback 함수를 사용하여, 수신된 지연된 딥링크의 처리를 위한 코드를 작성합니다.

// your code...

DOT.initializationForDeferredCallback(this, new Runnable() {
    @Override
    public void run() {
        // deferred deeplink  정보는 DOT.getDeferredUrl() 로 사용이 가능하며,
        // 앱에서는 해당 변수를 다음과 같이 사용할 수 있음. 
        // 1. callback 이 호출되는 시점에 즉시 __deferredUrl 화면으로 이동 처리. __deferredUrl 값이 nil 이면 메인 화면으로 이동 처리. 
        // 2. __deferredUrl 변수값을 어딘가에 저장하고, 회원가입 이후, 로그인이 완료된 이후등과 같이 필요한 시점에 저장된 값을 꺼내서 이동 처리.
        // 3. 사용 가능한 Deferred deeplink 정보가 없는 경우에는, __deferredUrl 값이 널(NULL) 이 될 수 있음을 고려하여 사용.          
        String __deferredUrl = DOT.getDeferredUrl();
        WiseLog.d("current deferred url : " + __deferredUrl);
    }
});

// your code...

위와 같이 지연된 딥링크에 대한 대응 코드가 적용된 이후에 와이즈트래커 대쉬보드에서 아래와 같이 어트리뷰션 링크를 생성하였다고 가정해보겠습니다.

지연된 딥링크(디퍼드 딥링크)가 사용된 어트리뷰션 링크이기 때문에 만약 앱이 설치되어 있지 않았던 경우라면, 먼저 앱 설치를 위해 마켓(구글스토어, 앱스토어)으로 이동되고, 앱 설치 이후에 앱을 실행시키게 되면 String __deferredUrl 변수에 설정한 앱 실행 링크가 들어가 있음을 확인할 수 있습니다. (예: wisetester://mainscreen)

따라서 들어가 있는 (디퍼드) 딥링크 값에 따라 어떻게 처리할지 이후 액션에 대해 대응되는 코드를 개발해 주시면 됩니다.

Facebook 광고 성과 측정

Facebook App Ads의 퍼포먼스를 와이즈트래커로 측정하는데 필요한 설정으로, Facebook SDK가 앱에 추가되어 있는 경우에만 설정을 적용할 수 있습니다.

비즈니스 인증

Facebook Developer 사이트의 앱설정-기본설정에서 비즈니스 인증 여부를 확인 해 주세요. 비즈니스 인증이 완료되지 않았을 경우, 리퍼러 정보가 수신되지 않아, facebook 광고 성과에 대한 측정이 어렵습니다.

설정 적용

프로젝트의 app/res/values/strings.xml 파일에 아래 설정을 추가합니다.

XML

 <!-- facebook AppLinkData 사용 여부  -->
    <string name="useFacebookAppLinkData">Y</string>

최초로 실행되는 Activity의 onCreate에 다음 코드를 추가해 주세요.

Java

import com.facebook.applinks.AppLinkData;

// call Facebook API
AppLinkData.fetchDeferredAppLinkData(getApplicationContext(), new AppLinkData.CompletionHandler() {
    @Override
    public void onDeferredAppLinkDataFetched(AppLinkData appLinkData) {
        if (appLinkData == null) {
            DOT.receiveFailFacebookReferrer(1);
            return ;
        }
        Bundle bundle = appLinkData.getArgumentBundle();
        if (bundle == null) {
            DOT.receiveFailFacebookReferrer(2);
            return;
        }
        DOT.setFacebookReferrer(bundle);
    }
});

Kotlin

데이터 확인

Facebook의 App Ads Helper로 Deferred Deep Linking 을 테스트 함으로써 위 설정이 올바르게 적용 되었는지를 확인할 수 있습니다.

준비사항

1. Android 테스트 단말기 환경

   • 단말기에 Facebook 앱을 설치하고 Facebook 개발자 계정으로 로그인해주세요.

   • 단말기에 테스트 대상 앱(고객사 앱)이 설치되어 있다면 삭제해주세요.

   • 개발자 모드와 USB 디버깅을 활성화 해주세요.

2. 데스크탑 환경

   • Android Studio를 설치해주세요.

   • USB로 연결된 테스트 단말기의 log를 Android Studio의 logcat으로 확인할 수 있어야 합니다.

3. Facebook 설정

   • 테스트 대상 앱이 Facebook Developer에 등록되어 있어야 합니다.

   • 개발자 계정으로 로그인하여 테스트를 진행합니다.

앱 설치형 광고 테스트

1. https://developers.facebook.com -> 도구 -> 앱 광고 지원 도구 메뉴로 이동합니다.

(https://developers.facebook.com/tools/app-ads-helper/)

1. 테스트할 앱을 선택한 후 페이지 하단 Developer Tool의 딥링크 테스트를 클릭합니다.

1. PC에서 Android Studio를 실행하고 테스트 단말기를 USB로 연결하여 관련 로그를 logcat으로 확인할 수 있도록 준비합니다. 앱이 수신한 Deep Link Referrer를 logcat에서 확인해야 하기 때문입니다.

2. Facebook 테스트 페이지로 돌아갑니다. 앱의 커스텀 스키마를 Send Deep Link에 입력하고 Send to Android 를 클릭합니다. 이 때 전송지연은 반드시 체크되어 있어야 합니다.

1. '전송지연'을 선택한 경우 Facebook 앱에 알림은 수신되지 않지만, 아래와 같은 팝업이 발생 하였다면 인스톨리퍼러 수신을 위한 준비가 완료 된 것입니다.

1. 안드로이드 스튜디오를 통해 해당 앱을 실행하고 로그를 확인 합니다. Facebook에 입력한 커스텀 스키마가 아래 그림처럼 logcat에서 보인다면 페이스북 앱 설치 광고에 대한 분석이 가능합니다.

앱 참여형 광고 테스트

1. 앱 참여 광고를 진행하는 경우 이미 앱을 설치한 사용자가 광고를 클릭하여 앱을 실행하는 시점에 페이스북 광고에 등록한 딥 링크값이 동작하는지 여부를 확인하면 됩니다.

2. 앱 참여 광고 등록 시 사용한 딥 링크를 Send Deep Link 영역에 입력 후 Send to Android 버튼을 클릭합니다. 이 때 전송 지연는 반드시 체크 해제되어 있어야 합니다.

3. 테스트 단말기의 Facebook 앱에 알림이 전송됩니다. 해당 링크를 클릭하여 앱을 실행합니다.

4. Facebook에 입력한 커스텀 스키마가 아래 그림처럼 logcat에서 보인다면 페이스북 앱 광고에 대한 분석이 가능합니다.