(ver 1.8.x) BuzzScreen Extension SDK 연동

개요

BuzzScreen Extension SDK는 개인화된 콘텐츠와 광고를 잠금화면에서 보여주는 BuzzScreen Android용 SDK의 동작을 돕는 익스텐션 SDK입니다.

M앱과 L앱에 각 SDK를 연동하면 M앱에서 설정한 사용자 정보를 L앱으로 동기화하여 L앱에서 버즈스크린을 사용하기 위해 필요한 사용자 정보를 가져올 수 있습니다. BuzzScreen Extension SDK는 잠금화면 전용 앱에서 직접 로그인을 구현하기 어려운 경우 기존 매체사 앱의 사용자 정보를 사용할 수 있도록 합니다.

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

  • 연동시 필요한 SDK

    • M앱 내 연동: BuzzScreenHost SDK

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

2) 요구 사양

항목

설명

항목

설명

1

안드로이드 지원 버전

Android 4.0.3 (API Level 15) 이상

2

APK의 서명

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

3

버즈빌 검수

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

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


M앱에 BuzzScreenHost 연동하기

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

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

1 단계. build.gradle 설정

manifestPlaceholders를 추가하세요.

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.8.+' // (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앱의 패키지명

아래의 코드 예제를 참고하세요.

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 단계. 사용자 정보 설정 및 동기화

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

항목

코드

호출 위치

설명

항목

코드

호출 위치

설명

사용자 정보 설정을 위한 객체

BuzzScreenHost.getUserProfile()

L앱 잠금화면을 활성화하기 전에 설정

사용자 정보를 설정할 수 있는 클래스인 UserProfile 호출

사용자 식별값 필수

setUserId(String userId)

  • 사용자에게 적립금을 지급하기 위한 필수적인 설정값

  • 매체사에서 사용자를 구분할 수 있는 식별값

  • 매체사 포인트 적립 포스트백 API 연동 요청 시에 전달됩니다. 포스트백 API 연동에 대한 자세한 내용은 매체사 포인트 적립 포스트백 API 연동 가이드를 참고하세요.

사용자 아이디가 설정되지 않으면 L앱은 M앱에서 로그인되지 않았다고 판단하고 NOT_ENOUGH_USER_INFO 오류를 발생시킵니다.

사용자 연령 권장

setBirthYear(int birthYear)

사용자의 출생 연도를 4자리의 숫자로 입력하여 나이를 설정합니다.

사용자 성별 권장

setGender(String gender)

미리 정의된 String 을 통해 형식에 맞추어 성별 설정합니다.

  • UserProfile.USER_GENDER_MALE : 남성

  • UserProfile.USER_GENDER_FEMALE : 여성

사용자 정보 동기화 필수

sync(boolean encrypt)

설정한 사용자 정보를 L앱으로 동기화합니다.

  • encrypt 선택 : 사용자 정보값 동기화 시 L앱에 전달하는 유저 정보를 암호화하기 위한 인자입니다.

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

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

아래의 코드 예제를 참고하세요.

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

4 단계. L앱 잠금화면 제어 설정

항목

코드

설명

항목

코드

설명

로그아웃 처리 필수

BuzzScreenHost.logout()

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

  • L앱의 잠금화면을 비활성화합니다.

  • M앱과 L앱에서 유저 정보를 삭제합니다.

L앱 실행 권장

BuzzScreenHost.launchClient()

L앱을 실행합니다.

  • L앱이 설치된 경우에는 L앱이 바로 실행합니다.

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

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

BuzzScreenHost.isClientActivated()

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

L앱 잠금화면 활성화 선택

BuzzScreenHost.requestActivation(OnRequestActivateResponseListener listener, boolean encrypt)

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

[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선택 : 잠금화면 활성화 시 L앱에 전달하는 유저 정보를 암호화하기 위한 인자

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

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

L앱 잠금화면 비활성화 선택

BuzzScreenHost.requestDeactivation()

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

 

L앱에 BuzzScreenClient 연동

항목

설명

항목

설명

1

유저 정보 설정

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

2

활성화/비활성화

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

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

요구 사양

항목

설명

항목

설명

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

3

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

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


1 단계. build.gradle 설정

1. manifestPlaceholders를 추가하세요.

2. dependencies를 추가하세요.

버즈스크린 연동

L앱을 위한 BuzzScreenClient 라이브러리

2 단계. 메소드 호출

버즈스크린을 Android 앱에 연동하기 위해서는 ​ 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()

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

 

아래의 코드 예제를 참고하세요.

 

2) 사용자 정보 설정

항목

코드

설명

항목

코드

설명

유저 정보 설정을 위한 객체

BuzzScreen.getInstance().getUserProfile()

유저 정보를 설정할 수 있는 클래스인 UserProfile 호출

  • 나이, 성별 정보를 설정하여 해당 유저에게 맞는 캠페인 타게팅 가능

유저 연령 권장

setBirthYear(int birthYear)

유저의 출생 년도를 4자리의 숫자로 입력하여 나이를 설정

유저 성별 권장

setGender(String gender)

미리 정의된 String 을 통해 형식에 맞추어 성별 설정

  • UserProfile.USER_GENDER_MALE : 남성

  • UserProfile.USER_GENDER_FEMALE : 여성

유저 정보 동기화 선택

BuzzScreenClient.requestUserProfileSync(boolean encrypt)

변경된 UserProfile 을 BuzzScreenHost에 전달해야 할 필요가 있을 때 호출

  • encrypt 선택 : 유저 정보값 동기화 시 M앱에 전달하는 유저 정보를 암호화하기 위한 인자

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

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

아래의 코드 예제를 참고하세요.

 

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

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

항목

코드 & 호출 위치

설명

항목

코드 & 호출 위치

설명

앱 위에 표시 권한 획득

BuzzScreen.getInstance().showOverlayPermissionGuideDialogIfNeeded(OverlayPermissionListener listener)

Android 10부터 변경된 정책에 따라, 잠금화면을 띄우기 위해서는 다른 앱 위에 표시 권한을 획득해야 합니다. 자세한 내용은 BuzzScreen SDK 연동 가이드의 다른 앱 위에 표시 권한 획득하기 토픽을 참고하세요.

버즈스크린 활성화에 필요한 유저정보 M앱에서 가져오기 필수

checkAvailability(OnCheckAvailabilityListener listener, boolean encrypt)

  • 호출 위치: L앱 진입화면의 onResume 에서 호출하여 L앱 진입 시 항상 수행되도록 함

비동기로 M앱에서 버즈스크린 활성화에 필요한 유저 정보들을 가져옵니다.

Parameters

  • OnCheckAvailabilityListener

    • onAvailable() : 버즈스크린을 활성화 할 수 있는 경우

    • onError(CheckAvailabilityError error) : 버즈스크린을 사용할 수 없는 경우

      • HOST_APP_NOT_INSTALLED

        • M앱이 설치되지 않은 경우, M앱의 설치를 유도해야 합니다.

      • HOST_NOT_SUPPORTED_VERSION

        • M앱에서 BuzzScreenHost 연동이 되지 않은 경우, M앱의 업데이트를 유도해야 합니다.

      • NOT_ENOUGH_USER_INFO

        • 버즈스크린을 활성화하는데 필수 정보인 userId가 M앱에서 설정되지 않은 경우, M앱에서 로그인을 통해 유저 정보를 설정해야 합니다.

      • UNKNOWN_ERROR : 잘못된 연동 혹은 일시적인 에러. 일시적인 에러인 경우에는 재시도를 유도해야 합니다.

        • buzzscreen-client 1.0.1 미만 버전: 잠금화면이 자동으로 비활성화됩니다.

        • buzzscreen-client 1.0.1 이상 버전: 비활성화 되지 않으므로, 유저가 사용할 수 있게 비활성화 버튼을 추가해야 합니다.

  • encrypt 선택 : 유저 정보값 확인 시 M앱으로부터 전달받는 유저 정보를 암호화하기 위한 인자입니다.

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

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

버즈스크린 활성화 필수

BuzzScreen.getInstance().activate()

이 함수가 호출된 이후부터 잠금화면에 버즈스크린이 나타납니다.

  • activate()를 처음 잠금화면 활성화 시 호출하면, 이후부터 자동으로 잠금화면 사이클이 관리되기 때문에 deactivate()를 호출하기 전에 다시 호출할 필요는 없습니다.

버즈스크린 비활성화 필수

BuzzScreen.getInstance().deactivate()

이 함수가 호출되면 더이상 잠금화면에 버즈스크린이 나타나지 않습니다.

아래의 코드 예제를 참고하세요.

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

Communication Utils Guide

  • BuzzScreen Extension SDK 에서는 M앱과 L앱 사이의 통신을 위한 유틸리티를 제공합니다.

buzzscreen-host, buzzscreen-client SDK 버전 1.8.0 이상부터 지원됩니다.

  • 이 유틸리티를 사용하면 M앱과 L앱은 서로를 통신의 엔드포인트로 등록을 하며, protectionLevel="signature" 인 커스텀 퍼미션을 사용하여 보안상 안전한 통신이 가능합니다.

  • 총 3종류의 상황에 적합한 유틸리티를 제공합니다.

    • 공유되는 데이터 저장소가 필요한 경우 : DataStorage

    • 단방향 이벤트 전달이 필요한 경우 : EventHandler

    • 완전한 서버-클라이언트 구조가 필요한 경우 : RequestHandler

DataStorage

  • 두 앱 사이에 공유되는 데이터 저장소가 필요한 경우 사용합니다.

  • 저장소에서는 key-value 구조로 데이터를 관리합니다.

BuzzScreen Extension SDK에서는 L앱의 잠금화면이 활성화 되어 있는지 여부를 확인할 때 사용하고 있습니다. L앱에서 잠금화면이 활성화 되거나 비활성화 될 때마다 DataStorage 에 값을 업데이트 시키며, M앱에서는 L앱의 상태를 확인하고 싶을 때 DataStorage 로부터 값을 읽습니다.

사용 방법

BuzzScreenHost.getDataStorage() 또는 BuzzScreenClient.getDataStorage()를 통해 DataStorage instance를 가져옵니다.

데이터 저장

  • void put(String key, String value) : key 에 매핑되는 value 를 저장합니다.

하나의 키에 대해서 put 은 반드시 한쪽에서만 호출해야 합니다. 각 앱은 put 을 호출하면 데이터를 자신의 저장소에 저장하며, get 을 호출하면 자신의 저장소를 검색한 후 값이 없으면 상대편 앱의 저장소를 검색합니다. 만약 같은 키에 대해 두 앱 모두에서 put 을 통해 서로 다른 값을 넣으면 서로 자신의 저장소에 각각 저장하므로 값이 공유가 되지 않습니다.

데이터 검색

  • String get(String key) : key 에 매핑된 value 를 Synchronous 하게 검색한 후 리턴합니다.

  • void getAsync(String key, DataStorage.AsyncQueryListener listener) : key 에 매핑된 value 를 Asynchronous 하게 검색해서 AsyncQueryListener 에 전달합니다.

    DataStorage 는 ContentProvider 를 사용하는데 ContentProvider 특성상 데이터 처리시 소요 시간이 길어질 수 있으므로 비동기 방법인 getAsync() 를 사용하는 것을 권장합니다.

    Parameters

    • AsyncQueryListener

      • void onQueryComplete(String value) : 검색이 완료되면 호출되며 파라미터로 value 가 전달됩니다(없을 경우 null 전달).

Code Example

아래 예제에서 BuzzScreenHostBuzzScreenClient는 바꾸어서 사용해도 됩니다.

EventHandler

  • Sender 로부터 Receiver 에게로 한쪽 방향으로만 이벤트를 전달하는 경우 사용합니다.

Sender, Receiver 역할은 특정 앱에 대해 고정된 것이 아니라 사용 방법에 따라 달라집니다.

  • 각 이벤트의 이름이 키가 되므로 Sender 와 Receiver 모두 하나의 이벤트에 대해 동일한 이벤트 이름을 사용해야 합니다.

  • 이벤트 전달시 추가적으로 넣을 정보는 Bundle 을 이용합니다.

BuzzScreen Extension SDK에서는 M앱에서 L앱의 잠금화면을 비활성화 시킬 때 사용하고 있습니다(BuzzScreenHost의 requestDeactivation()). L앱이 Receiver 로서 잠금화면을 비활성화시키는 로직을 구현해서 이벤트로 등록해 두고, M앱이 Sender 로서 해당 이벤트를 전송합니다.

사용 방법

BuzzScreenHost.getEventHandler() 또는 BuzzScreenClient.getEventHandler()를 통해 EventHandler instance를 가져옵니다.

이벤트 전송

  • void post(String eventName) : 이벤트를 Receiver 에게 보냅니다.

  • void post(String eventName, Bundle extras) : Bundle 형태의 추가 데이터를 담아서 이벤트를 Receiver 에게 보냅니다.

이벤트 수신

주의 : 반드시 Application Class 에서 호출되어야 합니다.

  • void registerEventListener(String eventName, EventHandler.OnEventListener listener) : 특정 이벤트를 받았을 때의 로직을 OnEventListener를 통해 구현해서 eventName과 매핑해 등록합니다.

    Parameters

    • OnEventListener

      • void onEvent(Bundle extras) : 이벤트를 받았을 때 호출되며 파라미터로 Sender 에서 보낸 추가 데이터가 전달됩니다(없을 경우 null 이 아닌 빈 Bundle 전달).

Code Example

아래 예제에서 BuzzScreenHostBuzzScreenClient는 바꾸어서 사용해도 됩니다.

RequestHandler

  • 서버-클라이언트 구조처럼 두 앱간 유기적인 요청과 응답 처리가 필요한 경우 사용합니다.

서버, 클라이언트 역할은 특정 앱에 대해 고정된 것이 아니라 사용 방법에 따라 달라집니다.

  • 각 요청과 응답 쌍은 request code 를 통해 구별이 되므로 서버와 클라이언트 모두 같은 request code를 사용해야 합니다.

  • 요청과 응답 시 주고받는 데이터는 Bundle 을 이용합니다.

BuzzScreen Extension SDK에서는 L앱에서 M앱의 버즈스크린 사용 정보를 가지고 올 때 사용하고 있습니다(BuzzScreenClient의 checkAvailability()). L앱이 클라이언트로서 M앱에 버즈스크린 사용 정보를 요청하며, M앱은 서버로서 이 요청을 받으면 버즈스크린 사용 정보를 담아 응답합니다. L앱은 이 응답을 통해 잠금화면을 활성화하는 등의 로직을 처리합니다.

사용 방법

BuzzScreenHost.getRequestHandler() 또는 BuzzScreenClient.getRequestHandler()를 통해 RequestHandler instance를 가져옵니다.

서버

주의 : 반드시 Application Class 에서 호출되어야 합니다.

  • void registerResponder(int requestCode, MsgRequestHandler.Responder responder) : 클라이언트로부터 요청이 왔을 때의 응답을 구현합니다.

    Parameters

    • requestCode : 요청을 구분하는 고유 코드

    • Responder

      • Bundle respond(Bundle parameters) : 클라이언트로부터 요청이 왔을 경우 호출되며, 파라미터로는 요청에 담긴 추가 파라미터가 전달됩니다. 클라이언트에 보낼 응답을 Bundle 에 담아서 리턴해야 합니다.

클라이언트

  • void request(int requestCode, Bundle params, Request.OnResponseListener listener) : 서버에 요청을 보내고, 요청에 대한 응답이 왔을 때의 콜백을 구현합니다.

    Parameters

    • requestCode : 요청을 구분하는 고유 코드

    • params : 요청시 보낼 데이터가 필요한 경우 Bundle 형태로 전달합니다.

    • OnResponseListener

      • void onResponse(Bundle response) : 서버 앱과의 통신에 성공한 경우 호출되며 파라미터로 서버의 응답 데이터가 전달됩니다(없을 경우 null 이 아닌 빈 Bundle 전달).

      • void onFail(Request.FailReason failReason) : 서버 앱과의 통신에 실패한 경우 호출됩니다. 실패의 원인이 파라미터로 전달됩니다.

Code Example

아래 예제에서 BuzzScreenHostBuzzScreenClient는 바꾸어서 사용해도 됩니다.