Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

목차

Introduction

Info

반드시 샘플 코드를 확인한 뒤 실제 퍼블리셔 앱의 코드에 연동 바랍니다. - M app / L app

...

Note

새로 BuzzScreen을 연동하는 퍼블리셔가 아니라 기존에 퍼블리셔 앱 내부에 BuzzScreen SDK를 연동했던 퍼블리셔들은 BuzzScreen Migration SDK 연동 문서를 참고해 주세요.

1) BuzzScreen SDK & BuzzScreen Extension SDK 작업 흐름

  • 연동시 필요한 SDK

    • M앱 내 연동: BuzzScreenHost SDK

    • L앱 내 연동: BuzzScreenClient SDK + BuzzScreen SDK

...

2) Requirements

항목

설명

1

안드로이드 지원 버전

Android 4.0.3 (API Level 15) 이상

2

APK의 서명

M앱과 L앱은 BuzzScreenHostBuzzScreenClient를 통해 서로 정보를 주고 받는데, 다른 앱에서의 접근을 막기 위해 반드시 동일한 서명으로 APK를 생성해야 합니다.

3

버즈빌 검수

가이드 내용을 모두 반영한 M앱과 L앱의 APK 파일들은 마켓에 업로드하기 전에 버즈빌 BD 팀에 전달하여 반드시 리뷰를 마친 후 마켓에 업로드 해야 합니다.

Info

SDK 연동 작업 전 반드시 미리 버즈빌 BD 매니저와 협의 부탁드립니다.

M앱에 BuzzScreenHost 연동

  • M앱에 연동하는 BuzzScreenHost는 L앱의 잠금화면 활성화에 필요한 정보들을 제공해주는 역할을 합니다.

  • L앱은 항상 실행 시에 M앱의 상태를 체크하여 L앱의 잠금화면 활성화 가능 여부를 판단합니다.

1. build.gradle 설정

manifestPlaceholders를 추가합니다.

Code Block
languagejava
android {
    defaultConfig {
        // my_app_key 에는 버즈스크린 연동 시 발급받은 앱키를 입력합니다.
        manifestPlaceholders = [buzzScreenAppKey:"my_app_key"]
    }
}
 
...
 
repositories {
    maven { url "https://dl.buzzvil.com/public/maven" }
}
 
...
 
dependencies { 
    // M앱을 위한 익스텐션 라이브러리, BuzzScreenHost. L앱과 다름에 주의!
    implementation 'com.buzzvil.buzzscreen.ext:buzzscreen-host:1.6.0'
 
    // (optional) Extension SDK에서 제공하는 암호화를 사용하는 경우, 아래의 library를 추가해 주어야 합니다.
    // implementation 'com.github.joshjdevl.libsodiumjni:libsodium-jni-aar:1.0.8'
}

2. Application Class에 코드 추가

항목

코드

호출 위치

설명

BuzzScreenHost의 초기화 코드

BuzzScreenHost.init(Application application, String clientPackageName)

Application 클래스

Parameters

  • application : Application을 this 로 전달

  • clientPackageName : L앱의 패키지명

Sample Code

Code Block
languagejava
public class App extends Application {
 
    @Override
    public void onCreate() {
        super.onCreate();
 
        // BuzzScreenHost 초기화
        // L앱의 패키지명이 com.buzzvil.buzzscreen.sample_client 인 경우 사용 예시
        BuzzScreenHost.init(this, "com.buzzvil.buzzscreen.sample_client");
         
        // Optional
        // L앱의 잠금화면이 활성화/비활성화되거나 L앱에서 유저 정보가 변경되는 경우 호출되는 리스너 등록 예시
        BuzzScreenHost.setClientEventListener(new BuzzScreenHost.ClientEventListener() {
            @Override
            public void onActivated() {
                // L앱의 잠금화면이 활성화된 경우 호출됨
                Log.i("MainApp", "ClientEventListener - onActivated");
            }
 
            @Override
            public void onDeactivated() {
                // L앱의 잠금화면이 비활성화된 경우 호출됨
                Log.i("MainApp", "ClientEventListener - onDeactivated");
            }
 
            @Override
            public void onUserProfileUpdated(UserProfile userProfile) {
                // L앱에서 유저 정보가 변경되는 경우 호출됨
                Log.i("MainApp", "ClientEventListener - onUserProfileUpdated");
            }
        });
    }
}

3. 유저 정보 설정 및 동기화

Note

만약 기존 유저 정보를 알 수 없는 경우 L앱에서 추가로 설정할 수도 있습니다. 단, 타게팅 정보를 어디에서도 설정하지 않는 경우 타게팅이 설정된 광고가 보이지 않으므로 유저가 볼 수 있는 전체 광고의 수량이 줄어들게 됩니다.

...

Code Block
languagejava
BuzzScreenHost.getUserProfile()
        .setUserId(newUserId)
        .setBirthYear(newBirthYear)
        .setGender(newGender)
        .sync(encrypt);

4. L앱 잠금화면 제어

항목

코드

설명

로그아웃 처리

Status
colourRed
title필수
필수

BuzzScreenHost.logout()

유저가 M앱에서 로그아웃하는 등 잠금화면을 사용할 수 없어지는 조건에서 호출

  • L앱의 잠금화면을 비활성화하고

  • M앱과 L앱에서 유저 정보를 삭제

L앱 실행

Status
colourYellow
title권장

BuzzScreenHost.launchClient()

L앱을 실행함

  • L앱이 설치된 경우에는 L앱이 바로 실행됨

  • L앱이 설치되지 않은 경우에는 마켓을 통해 설치 후 자동으로 실행됨

L앱 잠금화면 활성화 여부 확인

Status
title선택

BuzzScreenHost.isClientActivated()

L앱에서 잠금화면이 활성화되어 있으면 true, 비활성화되어 있으면 false를 리턴

L앱 잠금화면 활성화

Status
title선택

BuzzScreenHost.requestActivation(OnRequestActivateResponseListener listener, boolean encrypt)

M앱에서 설정한 유저 정보를 사용하여 L앱의 잠금화면을 활성화

Parameters

  • OnRequestActivateResponseListener

    • onAlreadyActivated() : L앱에서 버즈스크린이 이미 활성화가 되어있는 경우

    • onActivated() : L앱에서 버즈스크린이 활성화가 된 경우

    • onError(RequestActivationError error) : L앱의 버즈스크린 활성화에 실패한 경우

      • CLIENT_APP_NOT_INSTALLED : L앱이 설치되지 않아 활성화에 실패한 경우

      • CLIENT_NOT_SUPPORTED_VERSION : L앱에서 BuzzScreenClient 연동이 되지 않아 활성화에 실패한 경우

      • NOT_ENOUGH_USER_INFO : UserProfile 중 필수 정보인 유저 ID가 누락된 경우

      • UNKNOWN_ERROR : 잘못된 연동 혹은 일시적인 에러

  • encrypt

    Status
    title선택
    : 잠금화면 활성화 시 L앱에 전달하는 유저 정보를 암호화하기 위한 인자

    • v1.0.2.0 이상에서 사용 가능

    • 암호화하고자 하는 경우 encrypttrue를 전달하여 호출

L앱 잠금화면 비활성화

Status
title선택

BuzzScreenHost.requestDeactivation()

L앱에서 잠금화면이 활성화되어 있는 경우 해당 잠금화면을 비활성화

L앱 잠금화면 활성화 흐름

...

L앱에 BuzzScreenClient 연동

항목

내용

1

유저 정보 설정

M앱의 타게팅 정보를 설정하지 않았다면 L앱에서 직접 해당 정보를 유저로부터 획득하고 유저 타게팅 정보를 버즈스크린에 설정할 수 있습니다.

2

활성화/비활성화

  • L앱은 M앱으로부터 잠금화면에 필요한 정보를 획득하여 잠금화면을 활성화할 수 있습니다.

  • M앱에서 로그아웃 시점에 BuzzScreenHost.logout() 을 호출하는 경우, 혹은 M앱이 제거되거나 M앱의 데이터가 지워지는 경우 자동으로 L앱의 잠금화면이 비활성화됩니다.

Requirements

항목

세부내용

1

안드로이드 지원 버전

Android 4.0.3 (API Level 15) 이상

2

구글 플레이 서비스 버전 통일

아래 구글 플레이 서비스 버전은 퍼블리셔 앱에서 사용하는 구글 플레이 서비스 버전과 동일하도록 수정해야 합니다.

  • com.google.android.gms:play-services-base

  • com.google.android.gms:play-services-ads

  • com.google.android.gms:play-services-location

Note

설정하지 않을 경우 컴파일 시에 com.android.dex.DexException 등의 에러가 발생할 수 있음

3

Android Support Library 버전이 26 이상일 경우

GCM(Google Cloud Messaging) 쪽에서 불안정한 동작이 있으므로 play service version 을 12 이상으로 올려야 합니다.

Info

최신 버전인 15.0.1 을 권장합니다.

1. build.gradle 설정

1) manifestPlaceholders 추가

Code Block
languagejava
android {
    defaultConfig {
        // my_app_key 에는 버즈스크린 연동 시 발급받은 앱키를 입력합니다.
        manifestPlaceholders = [buzzScreenAppKey:"my_app_key"]
    }
}
 
...
 
repositories {
    maven { url "https://dl.buzzvil.com/public/maven" } //BuzzScreen SDK 1.8.9.0 이상 버젼 사용인 경우
}

2) dependencies 추가

버즈스크린 연동

Code Block
languagejava
dependencies {
    implementation 'com.buzzvil:buzzscreen:3.15.+'
}

L앱을 위한 BuzzScreenClient 라이브러리

Code Block
languagejava
dependencies {
    // L앱을 위한 BuzzScreenClient 라이브러리. BuzzScreenHost 와 버전이 반드시 일치해야 합니다.
    implementation 'com.buzzvil.buzzscreen.ext:buzzscreen-client:1.6.0'
 
    // (optional) Extension SDK에서 제공하는 암호화를 사용하는 경우, 아래의 library를 추가해 주어야 합니다.
    // implementation 'com.github.joshjdevl.libsodiumjni:libsodium-jni-aar:1.0.8'
}

2. 메소드 호출

버즈스크린을 안드로이드 앱에 연동하기 위해서는 ​ 1) 초기화 → 2) 유저 정보 설정 → 3) 잠금화면 제어 설정 의 세 단계를 따라야 합니다.

또한 M앱과의 사용자 정보 연동을 위해 BuzzScreenClient 역시 1) 단계에서 함께 초기화해야 합니다.

1) 초기화 : init() 호출 및 launch() 호출

항목

코드 & 호출 위치

설명

BuzzScreenClient 를 위한 L앱의 초기화 필수

BuzzScreenClient.init(Application application, String hostPackageName)

  • 호출 위치: BuzzScreen.init() 호출 이후

Parameters

  • application : Application을 this 로 전달

  • hostPackageName : M앱의 패키지명

M앱에 의한 비활성화 리스너 필수

BuzzScreenClient.setOnDeactivatedByHostListener(OnDeactivatedByHostListener listener)

Parameters

  • OnDeactivatedByHostListener

    • onDeactivated : L앱의 잠금화면이 비활성화될 때 호출됨

버즈스크린 실행 필수

BuzzScreen.getInstance().launch()

  • 호출 위치: 앱 실행시 처음 실행되는 액티비티에 추가

Sample Code

 BuzzScreenClient 를 위한 L앱의 초기화

...

Code Block
languagejava
public class StartActivity extends AppCompatActivity {   
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_start);
         
        // 앱 실행시 처음 실행되는 액티비티에 추가
        BuzzScreen.getInstance().launch();
    }
}

2) 유저 정보 설정

M앱에서 나이, 성별 정보를 모두 획득한 경우에는 이 항목을 건너뜁니다.

...

Code Block
languagejava
// get UserProfile from BuzzScreen
UserProfile userProfile = BuzzScreen.getInstance().getUserProfile();
 
// Update BuzzScreen UserProfile
userProfile.setBirthYear(newBirthYear);
userProfile.setGender(newGender);
 
// Optional : 변경된 UserProfile 을 Host에 전달해야 할 필요가 있을 때 호출
BuzzScreenClient.requestUserProfileSync(encrypt);

3) 잠금화면 활성화와 유저 정보 연동

L앱에서의 잠금화면 활성화는 M앱에서 정보 가져오기 → 버즈스크린 활성화 과정으로 진행됩니다.

...

Code Block
languagejava
public class MainActivity extends AppCompatActivity {
 
    private BuzzScreenClient buzzScreenClient = new BuzzScreenClient();
     
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
         
        // 본 예제에서는 MainActivity를 시작 Activity라고 가정하고 launch 메소드를 추가함
        BuzzScreen.getInstance().launch();
    }
         
    @Override
    protected void onResume() {
        super.onResume();
        buzzScreenClient.checkAvailability(new BuzzScreenClient.OnCheckAvailabilityListener() {
            @Override
            public void onAvailable() {
                // 버즈스크린을 활성화 할 수 있는 경우 호출됩니다.
                // 잠금화면 활성화에 필요한 흐름을 구성합니다.
                // 최종 잠금화면 활성화는 BuzzScreen.getInstance().activate()를 통해 동작합니다.
            }
 
            @Override
            public void onError(BuzzScreenClient.CheckAvailabilityError error) {
                switch (error) {
                    case HOST_APP_NOT_INSTALLED:
                        sendToPlayStore("앱이 설치되어 있지 않습니다.\n설치 링크로 이동합니다.");
                        break;
                    case HOST_NOT_SUPPORTED_VERSION:
                        sendToPlayStore("앱이 최신 버전이 아닙니다.\n설치 링크로 이동합니다.");
                        break;
                    case NOT_ENOUGH_USER_INFO:
                        // M App 을 통해 유저 정보를 받을 수 있도록 합니다.
                        sendToMain();
                        break;
                    case UNKNOWN_ERROR:
                        Toast.makeText(MainActivity.this, "에러가 발생했습니다. 다시 시도해주세요.", Toast.LENGTH_SHORT).show();
                        break;
                }
            }
        });
    }
     
    @Override
    public void onPause() {
        super.onPause();
        // checkAvailability 를 중단하기위해 호출합니다.
        // 여기서 중단하지 않으면 onAvailable or onError 가 호출됩니다.
        buzzScreenClient.pause();   
    }
}

L앱 checkAvailability와 잠금화면 활성화 흐름

...