Introduction

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

개인화된 콘텐츠와 광고를 안드로이드 잠금화면에서 보여주는 버즈스크린 SDK의 동작을 돕는 익스텐션 SDK입니다.
M앱과 L앱에 각 SDK를 연동하면 M앱에서 설정한 사용자 정보를 L앱으로 동기화하여 L앱에서 버즈스크린을 사용하는 데에 필요한 사용자 정보를 가져올 수 있습니다. 버즈스크린에 유저 정보를 전달하기 위해서는 다음 두 가지 방법 중 하나를 사용합니다.
1. 락스크린 전용 애플리케이션에서 직접 로그인 기능을 구현 - https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/384860182 문서 참고
2. 락스크린 전용 애플리케이션에서 직접 로그인을 구현하기 어려운 경우 기존 퍼블리셔 앱의 유저 정보를 사용 할 수 있도록 BuzzScreen Extension SDK 사용 - 현재 가이드 참고

새로 BuzzScreen을 연동하는 퍼블리셔가 아니라 기존에 퍼블리셔 앱 내부에 BuzzScreen SDK를 연동했던 퍼블리셔들은 https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/386924671 문서를 참고해 주세요.

1 Introduction
2 M앱에 BuzzScreenHost 연동
3 L앱에 BuzzScreenClient 연동
- 3.1 1. build.gradle 설정
- 3.2 2. 메소드 호출

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앱은 `BuzzScreenHost`와 `BuzzScreenClient`를 통해 서로 정보를 주고 받는데, 다른 앱에서의 접근을 막기 위해 반드시 동일한 서명으로 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.4.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

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)`		유저에게 적립금을 지급하기 위한 필수적인 설정값 매체사에서 유저를 구분할 수 있는 식별값 https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/1756004654 요청 시에 전달됨 앱 재설치 또는 일정 주기에 따라 `userId` 가 변화할 경우, 반드시 BD 매니저와 사전 논의 필요 유저아이디가 설정되지 않으면 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 이상에서 사용 가능 암호화하고자 하는 경우 `encrypt`에 `true`를 전달하여 호출

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앱의 잠금화면을 활성화 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 이상에서 사용 가능 암호화하고자 하는 경우 `encrypt`에 `true`를 전달하여 호출
L앱 잠금화면 비활성화 선택	`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` 설정하지 않을 경우 컴파일 시에 `com.android.dex.DexException` 등의 에러가 발생할 수 있음
3	Android Support Library 버전이 26 이상일 경우	GCM(Google Cloud Messaging) 쪽에서 불안정한 동작이 있으므로 play service version 을 12 이상으로 올려야 합니다. 최신 버전인 15.0.1 을 권장

1. `build.gradle` 설정

1) `manifestPlaceholders` 추가

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` 추가

버즈스크린 연동

L앱을 위한 BuzzScreenClient 라이브러리

dependencies {
    // L앱을 위한 BuzzScreenClient 라이브러리. BuzzScreenHost 와 버전이 반드시 일치해야 합니다.
    implementation 'com.buzzvil.buzzscreen.ext:buzzscreen-client:1.4.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

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        ...
        // app_key : SDK 사용을 위한 앱키로, 어드민에서 확인 가능
        // SimpleLockerActivity.class : 잠금화면 액티비티 클래스
        // R.drawable.image_on_fail : 네트워크 에러 혹은 일시적으로 잠금화면에 보여줄 캠페인이 없을 경우 보여주게 되는 이미지.
        BuzzScreen.init("app_key", this, SimpleLockerActivity.class, R.drawable.image_on_fail);
        
        // BuzzScreenClient를 위한 코드
        // M앱의 패키지명이 com.buzzvil.buzzscreen.sample_host 인 경우 사용 예시
        BuzzScreenClient.init(this, "com.buzzvil.buzzscreen.sample_host");        
        
        // Optional
        BuzzScreenClient.setHostEventListener(new BuzzScreenClient.HostEventListener() {
          @Override
          public void onLogout() {
            // M앱에서 로그아웃되는 경우 호출됩니다.
          }
        });
        
        // Optional
        BuzzScreenClient.setOnDeactivatedByHostListener(new BuzzScreenClient.OnDeactivatedByHostListener() {
          @Override
          public void onDeactivated() {
            // M앱에 의해 잠금화면이 비활성화되는 경우 호출됩니다.
          }
        });
    }
}

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

2) 유저 정보 설정

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

나이, 성별 정보를 M앱, L앱 어디에서도 설정하지 않는 경우 타게팅이 설정된 광고가 보이지 않으므로 유저가 볼 수 있는 전체 광고의 수량이 줄어들게 됩니다.

항목	코드	세부내용

항목	코드	세부내용
유저 정보 설정을 위한 객체	`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 이상에서 사용 가능 암호화하고자 하는 경우 `encrypt`에 `true`를 전달하여 호출

// 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앱에서 정보 가져오기 → 버즈스크린 활성화 과정으로 진행됩니다.

항목	코드 & 호출 위치	세부내용

항목

코드 & 호출 위치

세부내용

버즈스크린 활성화에 필요한 유저정보 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 이상에서 사용 가능
- 암호화하고자 하는 경우 encrypt에 true를 전달하여 호출

버즈스크린 활성화 필수

BuzzScreen.getInstance().activate()

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

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

버즈스크린 비활성화 필수

BuzzScreen.getInstance().deactivate()

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

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();    
    }
}

BuzzScreen Extension SDK 연동

Introduction

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

2) Requirements

M앱에 BuzzScreenHost 연동

1. `build.gradle` 설정

2. Application Class에 코드 추가

Sample Code

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

4. L앱 잠금화면 제어

L앱 잠금화면 활성화 흐름

L앱에 BuzzScreenClient 연동

Requirements

1. `build.gradle` 설정

1) `manifestPlaceholders` 추가

2) `dependencies` 추가

버즈스크린 연동

L앱을 위한 BuzzScreenClient 라이브러리

2. 메소드 호출

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

Sample Code

2) 유저 정보 설정

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

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

BuzzScreen Extension SDK 연동

Introduction

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

2) Requirements

M앱에 BuzzScreenHost 연동

1. build.gradle 설정

2. Application Class에 코드 추가

Sample Code

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

4. L앱 잠금화면 제어

L앱 잠금화면 활성화 흐름

L앱에 BuzzScreenClient 연동

Requirements

1. build.gradle 설정

1) manifestPlaceholders 추가

2) dependencies 추가

버즈스크린 연동

L앱을 위한 BuzzScreenClient 라이브러리

2. 메소드 호출

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

Sample Code

2) 유저 정보 설정

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

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

1. `build.gradle` 설정

1. `build.gradle` 설정

1) `manifestPlaceholders` 추가

2) `dependencies` 추가

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

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