목차
Introduction
반드시 샘플 코드를 확인한 뒤 실제 퍼블리셔 앱의 코드에 연동 바랍니다. - M app / L app |
개인화된 콘텐츠와 광고를 안드로이드 잠금화면에서 보여주는 버즈스크린 SDK의 동작을 돕는 익스텐션 SDK입니다.
M앱과 L앱에 각 SDK를 연동하면 M앱에서 설정한 사용자 정보를 L앱으로 동기화하여 L앱에서 버즈스크린을 사용하는 데에 필요한 사용자 정보를 가져올 수 있습니다. 버즈스크린에 유저 정보를 전달하기 위해서는 다음 두 가지 방법 중 하나를 사용합니다.
락스크린 전용 애플리케이션에서 직접 로그인 기능을 구현 - BuzzScreen SDK 기본 설정 문서 참고
락스크린 전용 애플리케이션에서 직접 로그인을 구현하기 어려운 경우 기존 퍼블리셔 앱의 유저 정보를 사용 할 수 있도록 BuzzScreen Extension SDK 사용 - 현재 가이드 참고
1) BuzzScreen SDK & BuzzScreen Extension 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 연동
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.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 |
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)
| 앱 재설치 또는 일정 주기에 따라 userId 가 변화할 경우, 반드시 BD 매니저와 사전 논의 필요 |
유저 아이디가 설정되지 않으면 L앱은 M앱에서 로그인되지 않았다고 판단하고 NOT_ENOUGH_USER_INFO 에러를 발생시킴 |
|
유저 연령 | setBirthYear(int birthYear)
| 유저의 출생 년도를 4자리의 숫자로 입력하여 나이를 설정 |
유저 성별 | setGender(String gender)
| 미리 정의된 String 을 통해 형식에 맞추어 성별 설정 |
유저 정보 동기화 필수 | sync(boolean encrypt)
| 설정한 유저 정보를 L앱으로 동기화 동기화는 반드시 유저 정보 설정과 동시에 이뤄져야 함 |
|
BuzzScreenHost.getUserProfile()
.setUserId(newUserId)
.setBirthYear(newBirthYear)
.setGender(newGender)
.sync(encrypt); |
|
4. L앱 잠금화면 제어
항목 | 코드 | 설명 |
---|
로그아웃 처리 필수 | BuzzScreenHost.logout()
| 유저가 M앱에서 로그아웃하는 등 잠금화면을 사용할 수 없어지는 조건에서 호출 L앱의 잠금화면을 비활성화하고 M앱과 L앱에서 유저 정보를 삭제
|
L앱 실행 | BuzzScreenHost.launchClient()
| L앱을 실행함 |
L앱 잠금화면 활성화 여부 확인 | BuzzScreenHost.isClientActivated()
| L앱에서 잠금화면이 활성화되어 있으면 true , 비활성화되어 있으면 false 를 리턴 |
L앱 잠금화면 활성화 | BuzzScreenHost.requestActivation(OnRequestActivateResponseListener listener, boolean encrypt)
| M앱에서 설정한 유저 정보를 사용하여 L앱의 잠금화면을 활성화 Parameters |
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 이상으로 올려야 합니다. |
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
추가
버즈스크린 연동
dependencies {
implementation 'com.buzzvil:buzzscreen:3.15.+'
} |
|
L앱을 위한 BuzzScreenClient 라이브러리
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)
| Parameters |
M앱에 의한 비활성화 리스너 필수 | BuzzScreenClient.setOnDeactivatedByHostListener(OnDeactivatedByHostListener listener)
| Parameters |
버즈스크린 실행 필수 | BuzzScreen.getInstance().launch()
| |
Sample Code
BuzzScreenClient 를 위한 L앱의 초기화
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 을 통해 형식에 맞추어 성별 설정 |
유저 정보 동기화 | BuzzScreenClient.requestUserProfileSync(boolean encrypt)
| 변경된 UserProfile 을 BuzzScreenHost에 전달해야 할 필요가 있을 때 호출 |
// 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)
| 비동기로 M앱에서 버즈스크린 활성화에 필요한 유저 정보들을 가져옴 Parameters |
버즈스크린 활성화 필수 | BuzzScreen.getInstance().activate()
| 이 함수가 호출된 이후부터 잠금화면에 버즈스크린이 나타남 |
버즈스크린 비활성화 필수 | BuzzScreen.getInstance().deactivate()
| 이 함수가 호출되면 더이상 잠금화면에 버즈스크린이 나타나지 않음 |
Sample Code
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
와 잠금화면 활성화 흐름