(ver 1.7.x) BuzzScreen Extension SDK 연동
개요
BuzzScreen Extension SDK는 개인화된 콘텐츠와 광고를 잠금화면에서 보여주는 BuzzScreen Android용 SDK의 동작을 돕는 익스텐션 SDK입니다.
M앱과 L앱에 각 SDK를 연동하면 M앱에서 설정한 사용자 정보를 L앱으로 동기화하여 L앱에서 버즈스크린을 사용하기 위해 필요한 사용자 정보를 가져올 수 있습니다. BuzzScreen Extension SDK는 잠금화면 전용 앱에서 직접 로그인을 구현하기 어려운 경우 기존 매체사 앱의 사용자 정보를 사용할 수 있도록 합니다.
잠금화면 전용 앱에서 직접 로그인 기능을 구현할 수 있는 경우에는 BuzzScreen 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앱은 |
| 3 | 버즈빌 검수 | 가이드 내용을 모두 반영한 M앱과 L앱의 APK 파일들은 마켓에 업로드하기 전에 버즈빌 BD 팀에 전달하여 반드시 리뷰를 마친 후 마켓에 업로드 해야 합니다. |
SDK 연동 작업 전 반드시 미리 버즈빌 BD 매니저와 협의 부탁드립니다.
M앱에 BuzzScreenHost 연동하기
M앱에 연동하는
BuzzScreenHost는 L앱의 잠금화면 활성화에 필요한 정보들을 제공해주는 역할을 합니다.L앱은 항상 실행 시에 M앱의 상태를 체크하여 L앱의 잠금화면 활성화 가능 여부를 판단합니다.
1 단계. build.gradle 설정
manifestPlaceholders를 추가하세요.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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.7.1'
// (optional) Extension SDK에서 제공하는 암호화를 사용하는 경우, 아래의 library를 추가해 주어야 합니다.
// implementation 'com.github.joshjdevl.libsodiumjni:libsodium-jni-aar:1.0.8'
}2 단계. Application Class에 코드 추가
|
| Application 클래스 | Parameters
|
아래의 코드 예제를 참고하세요.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
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앱에서 추가로 설정할 수도 있습니다. 단, 타게팅 정보를 어디에서도 설정하지 않는 경우 타게팅이 설정된 광고가 보이지 않으므로 유저가 볼 수 있는 전체 광고의 수량이 줄어들게 됩니다.
사용자 정보 설정을 위한 객체 |
| L앱 잠금화면을 활성화하기 전에 설정 | 사용자 정보를 설정할 수 있는 클래스인 |
사용자 식별값 필수 |
|
앱 재설치 또는 일정 주기에 따라 사용자 아이디가 설정되지 않으면 L앱은 M앱에서 로그인되지 않았다고 판단하고 | |
사용자 연령 권장 |
| 사용자의 출생 연도를 4자리의 숫자로 입력하여 나이를 설정합니다. | |
사용자 성별 권장 |
| 미리 정의된 String 을 통해 형식에 맞추어 성별 설정합니다.
| |
사용자 정보 동기화 필수 |
| 설정한 사용자 정보를 L앱으로 동기화합니다. 동기화는 반드시 유저 정보 설정과 동시에 이뤄져야 합니다.
|
아래의 코드 예제를 참고하세요.
1
2
3
4
5
BuzzScreenHost.getUserProfile()
.setUserId(newUserId)
.setBirthYear(newBirthYear)
.setGender(newGender)
.sync(encrypt);4 단계. L앱 잠금화면 제어 설정
로그아웃 처리 필수 |
| 유저가 M앱에서 로그아웃하는 등 잠금화면을 사용할 수 없어지는 조건에서 호출
|
L앱 실행 권장 |
| L앱을 실행합니다.
|
L앱 잠금화면 활성화 여부 확인 선택 |
| L앱에서 잠금화면이 활성화되어 있으면 |
L앱 잠금화면 활성화 선택 |
| M앱에서 설정한 유저 정보를 사용하여 L앱의 잠금화면을 활성화합니다. [L앱 잠금화면 활성화 흐름] Parameters
|
L앱 잠금화면 비활성화 선택 |
| L앱에서 잠금화면이 활성화되어 있는 경우 해당 잠금화면을 비활성화합니다. |
L앱에 BuzzScreenClient 연동
| 1 | 유저 정보 설정 | M앱의 타게팅 정보를 설정하지 않았다면 L앱에서 직접 해당 정보를 유저로부터 획득하고 유저 타게팅 정보를 버즈스크린에 설정할 수 있습니다. |
| 2 | 활성화/비활성화 |
|
요구 사양
| 1 | 안드로이드 지원 버전 | Android 4.0.3 (API Level 15) 이상 |
| 2 | 구글 플레이 서비스 버전 통일 | 아래 구글 플레이 서비스 버전은 퍼블리셔 앱에서 사용하는 구글 플레이 서비스 버전과 동일하도록 수정해야 합니다.
설정하지 않을 경우 컴파일 시에 |
| 3 | Android Support Library 버전이 26 이상일 경우 | GCM(Google Cloud Messaging) 쪽에서 불안정한 동작이 있으므로 play service version을 12 이상으로 업데이트해야 합니다. 최신 버전인 15.0.1 을 권장합니다. |
1 단계. build.gradle 설정
1. manifestPlaceholders를 추가하세요.
1
2
3
4
5
6
7
8
9
10
11
12
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 라이브러리
1
2
3
4
5
6
7
dependencies {
// L앱을 위한 BuzzScreenClient 라이브러리. BuzzScreenHost 와 버전이 반드시 일치해야 합니다.
implementation 'com.buzzvil.buzzscreen.ext:buzzscreen-client:1.7.1'
// (optional) Extension SDK에서 제공하는 암호화를 사용하는 경우, 아래의 library를 추가해 주어야 합니다.
// implementation 'com.github.joshjdevl.libsodiumjni:libsodium-jni-aar:1.0.8'
}2 단계. 메소드 호출
버즈스크린을 Android 앱에 연동하기 위해서는 1) 초기화 → 2) 유저 정보 설정 → 3) 잠금화면 제어 설정 의 세 단계를 따라야 합니다.
또한 M앱과의 사용자 정보 연동을 위해 BuzzScreenClient 역시 1) 단계에서 함께 초기화해야 합니다.
1) 초기화 : init() 호출 및 launch() 호출
BuzzScreenClient 를 위한 L앱의 초기화 필수 |
| Parameters
|
M앱에 의한 비활성화 리스너 필수 |
| Parameters
|
버즈스크린 실행 필수 |
|
|
아래의 코드 예제를 참고하세요.
2) 사용자 정보 설정
M앱에서 나이, 성별 정보를 모두 획득한 경우에는 이 항목을 건너뜁니다.
나이, 성별 정보를 M앱, L앱 어디에서도 설정하지 않는 경우 타게팅이 설정된 광고가 보이지 않으므로 유저가 볼 수 있는 전체 광고의 수량이 줄어들게 됩니다.
유저 정보 설정을 위한 객체 |
| 유저 정보를 설정할 수 있는 클래스인
|
유저 연령 권장 |
| 유저의 출생 년도를 4자리의 숫자로 입력하여 나이를 설정 |
유저 성별 권장 |
| 미리 정의된 String 을 통해 형식에 맞추어 성별 설정
|
유저 정보 동기화 선택 |
| 변경된 UserProfile 을 BuzzScreenHost에 전달해야 할 필요가 있을 때 호출
|
아래의 코드 예제를 참고하세요.
1
2
3
4
5
6
7
8
9
// 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앱에서 정보 가져오기 → 버즈스크린 활성화 과정으로 진행됩니다.
앱 위에 표시 권한 획득 |
| Android 10부터 변경된 정책에 따라, 잠금화면을 띄우기 위해서는 다른 앱 위에 표시 권한을 획득해야 합니다. 자세한 내용은 BuzzScreen SDK 연동 가이드의 다른 앱 위에 표시 권한 획득하기 토픽을 참고하세요. L앱에서는 M앱에서도 잠금화면 활성화 호출이 가능하므로, 이 권한 획득을 SplashActivity 등 앱 실행 시 나타나는 첫 화면, 즉 가장 빠른 시점에 필수적으로 받고, 권한 획득이 안 된 경우에는 앱 사용을 할 수 없게 종료하는 등의 구현을 권장합니다. |
버즈스크린 활성화에 필요한 유저정보 M앱에서 가져오기 필수 |
| 비동기로 M앱에서 버즈스크린 활성화에 필요한 유저 정보들을 가져옵니다. Parameters
|
버즈스크린 활성화 필수 |
| 이 함수가 호출된 이후부터 잠금화면에 버즈스크린이 나타납니다.
|
버즈스크린 비활성화 필수 |
| 이 함수가 호출되면 더이상 잠금화면에 버즈스크린이 나타나지 않습니다. |
아래의 코드 예제를 참고하세요.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
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와 잠금화면 활성화 흐름