BuzzScreen Migration SDK 연동
- Jen Yoon (Unlicensed)
- Olivia Kim
- Ryan Ko (Unlicensed)
Introduction
반드시 버즈빌 BD 팀과 협의 후 진행해야 하며, 가이드를 반영한 M앱과 L앱의 APK 파일을 마켓에 업로드하기 전에 버즈빌 BD 팀에 전달하여 반드시 리뷰를 거쳐야 합니다.
구글 정책 대응을 위해, 기존 버즈스크린을 연동한 어플리케이션의 잠금화면을 새로운 잠금화면 전용 어플리케이션의 잠금화면으로 마이그레이션 하기 위한 가이드입니다. 아래의 사항을 숙지한 후 연동을 진행해주세요.
용어 정의
이하 기존 버즈스크린을 연동한 어플리케이션을 “M(Main) 앱”으로 지칭하고,
새로운 잠금화면 전용 어플리케이션을 “L(LockScreen) 앱”으로 지칭합니다.
요약: 이 SDK 의 연동작업을 통해, M앱의 버즈스크린 사용자를 L앱의 버즈스크린 사용자로 자연스럽게 & 최소한의 연동 코스트로 전환 가능합니다.
사용 상황: L앱 내에 자체 로그인 기능 구현이 어렵거나 / M앱의 로그인 관리를 그대로 L앱에서 사용하고 싶은 경우
필요한 유저 정보(유저아이디, 나이, 성별 등) 및 잠금화면 활성화 동의 여부를 M앱에서 수집하여 L앱으로 가져올 수 있도록 SDK에서 지원합니다. 따라서 L앱의 자체 로그인 시스템이 불필요합니다.
보안: 다른 앱에서의 접근을 막기 위해 안드로이드의
protectionLevel="signature"권한을 사용합니다.참고: L앱의 설치 (APK 파일 다운로드 & 설치) 는 유저의 액션 없이 진행할 수 없기에 자동화가 불가능합니다.
Migration SDK Workflow
- 1 Introduction
- 2 M앱 마이그레이션 구현
- 2.1 Basic Usage
- 2.2 Advanced Usage
- 3 L앱 마이그레이션 구현
- 3.1 Basic Usage
- 3.2 Advanced Usage
- 3.3 Appendix
M앱 마이그레이션 구현
Basic Usage
버즈스크린 연동에 필요한 유저 프로필 정보는 기존처럼 M앱에서 수집하고, 마이그레이션 SDK를 통해 L앱으로 자동으로 전달됩니다.
M앱은 마이그레이션 이후에도 L앱에서 잠금화면 활성화에 필요한 정보들을 제공해주는 역할을 합니다.
L앱은 항상 실행 시에 M앱의 상태를 체크하여 L앱의 잠금화면 활성화 가능 여부를 판단합니다.
1. build.gradle 설정
1) manifestPlaceholders 추가
android {
defaultConfig {
// my_app_key 에는 버즈스크린 연동 시 발급받은 앱키를 입력합니다.
manifestPlaceholders = [buzzScreenAppKey:"my_app_key"]
}
}2) dependencies 에 추가
M앱을 위한 마이그레이션 라이브러리를 추가하고, BuzzScreen SDK 버전 1.6.3 이상으로 업데이트해야 합니다.
기존 버즈스크린 연동
M앱을 위한 마이그레이션 라이브러리
repositories {
maven { url "https://dl.buzzvil.com/public/maven" }
}
...
dependencies {
// 라이브러리명이 L앱과 다름에 주의!
implementation 'com.buzzvil.buzzscreen.ext:migration-host:1.4.0'
// (optional) migration SDK에서 제공하는 암호화를 사용하는 경우, 아래의 library를 추가해 주어야 합니다.
// implementation 'com.github.joshjdevl.libsodiumjni:libsodium-jni-aar:1.0.8'
}
2. Application Class 에 코드 추가
기존 버즈스크린 연동을 위해 추가한 BuzzScreen.init 다음에 MigrationHost.init을 호출합니다.
MigrationHost.init(Context context, String lockScreenPackageName): 마이그레이션을 위한 M앱의 초기화 코드Parameters
context: Application context 를 this 로 전달lockScreenPackageName: L앱의 패키지명
사용 예시
public class App extends Application { @Override public void onCreate() { super.onCreate(); // 기존 버즈스크린 초기화 코드. BuzzScreen.init("app_key", this, SimpleLockerActivity.class, R.drawable.image_on_fail); // 마이그레이션을 위한 초기화 // L앱의 패키지명이 com.buzzvil.buzzscreen.sample_lock_light 인 경우 사용 예시 MigrationHost.init(this, "com.buzzvil.buzzscreen.sample_lock_light"); // L앱에서 버즈스크린이 활성화되어 M앱에서 잠금화면이 비활성화 되는 경우 호출되는 리스너 등록 예시 MigrationHost.setOnDeactivatedByLockScreenAppListener(new MigrationHost.OnDeactivatedByLockScreenAppListener() { @Override public void onDeactivated() { Log.i("MainApp", "LockScreen is deactivated by LockScreen App"); } }); } }
3. 잠금화면 활성화 화면 변경
L앱은 M앱의 유저 정보로 잠금화면을 활성화 할 뿐 직접 유저에게 정보나 동의를 받는 과정이 없습니다. 이 때문에 L앱에서는 M앱의 잠금화면 활성화 화면 (유저 프로필, 사용동의, 활성화/비활성화 설정 화면) 을 변경하여 사용하게 됩니다.
항목 | 코드 | 내용 | |
|---|---|---|---|
| 1 | M앱의 잠금화면 활성화 화면으로 이동하는 딥링크 설정 | - |
|
| 2 | L앱을 통해 잠금화면 활성화 |
| 앱 내의 잠금화면 활성화 화면에서 활성화/비활성화를 설정하는 스위치를 배너 형태로 변경합니다. 해당 배너 클릭 시, 혹은 잠금화면 사용 동의를 받고 잠금화면을 활성화 하는 곳 (기존
|
L앱 잠금화면 활성화 과정
4. 로그아웃 처리
M앱에서 로그아웃이 일어나는 경우 아래 두 함수를 호출합니다.
L앱에서의 잠금화면을 비활성화하고, 다음 활성화 시에 L앱에서 새로운 유저 정보를 M앱으로부터 제공받기 위함입니다.
BuzzScreen.getInstance().logout(): M앱에서 잠금화면을 비활성화하고, 유저정보를 초기화합니다.MigrationHost.requestDeactivation(): L앱에서 잠금화면이 활성화되어 있는 경우 해당 잠금화면을 비활성화합니다.
+. 버즈스크린 활성화/비활성화 관련 코드 제거 선택
M앱에서 L앱으로의 마이그레이션 이후 M앱의 잠금화면을 지원하지 않을 경우, 잠금화면 활성화/비활성화를 위해 삽입했던 BuzzScreen.getInstance().activate(), BuzzScreen.getInstance().deactivate() 코드를 모두 제거합니다.
Advanced Usage
그 외 유용한 함수들
항목 | 코드 | 내용 |
|---|---|---|
L앱의 잠금화면 활성화 여부 확인 |
|
|
M앱에서 변경된 유저 아이디를 L앱에 동기화 |
| 기존 M앱에서 주기적으로 유저 아이디가 변경되는 경우에는,
이 함수를 호출하지 않으면 L앱에서는 다음 |
커스텀 마켓 링크 설정 |
|
|
L앱의 실행 없이 L앱의 잠금화면 활성화 |
| 잠금화면을 활성화 할때는 M앱에서 설정된 유저 정보를 사용하게 됩니다.
|
L앱 마이그레이션 구현
항목 | 내용 | |
|---|---|---|
| 1 | 유저정보 설정 및 사용 동의 |
|
| 2 | 활성화/비활성화 |
|
| 3 | L앱 구현 |
|
Basic Usage
1. build.gradle 설정
1) manifestPlaceholders 추가
2) dependencies 추가
L앱을 위한 마이그레이션 라이브러리뿐만 아니라 버즈스크린 라이브러리도 추가합니다. BuzzScreen SDK 1.6.3 버전 이상이 필요합니다.
버즈스크린 연동
L앱을 위한 마이그레이션 라이브러리
2. AndroidManifest.xml 변경
버즈스크린 연동을 위해 app_license는 새로 발급 받아 L앱에 적용해야 합니다. 버즈빌 BD 매니저에게 문의해주세요.
3. Application Class 에 코드 추가
버즈스크린 연동을 위한 BuzzScreen.init 와 마이그레이션 연동을 위한 MigrationClient.init를 순서대로 호출합니다.
항목 | 코드 & 호출 위치 | 세부내용 |
|---|---|---|
마이그레이션을 위한 L앱의 초기화 코드 필수 |
| Parameters
|
L앱에서의 잠금화면이 비활성화되는 경우의 리스너 등록 필수 |
| 호출되는 경우
Parameters
|
4. 잠금화면 활성화와 마이그레이션
L앱에서의 잠금화면 활성화는 1) M앱에서 정보 가져오기 → 2) 버즈스크린 활성화 과정으로 진행됩니다.
L앱이 실행될 때 이 과정이 진행되면서 마이그레이션이 되고, 이후에도 M앱의 정보를 통해 L앱의 잠금화면을 활성화시키게 됩니다.
L앱의 잠금화면이 활성화되면 자동으로 M앱의 잠금화면이 비활성화 됩니다.
M앱의 정보를 가져오기 위해 MigrationClient에서 다음 함수를 제공합니다.
checkAvailability(OnCheckAvailabilityListener listener, boolean encrypt)호출 위치: L앱 진입화면의
onResume에서 호출하여 L앱 진입 시 항상 수행되도록 합니다.비동기로 M앱에서 버즈스크린 활성화에 필요한 정보들을 가져오고, M앱의 상태에 따라 자동으로 잠금화면을 활성화합니다.
자동으로 잠금화면 활성화 되는 조건
M앱에서 잠금화면을 사용 중인 경우
MigrationHost.requestActivationWithLaunch()를 호출하여 L앱을 실행한 경우
파라미터 | 리스폰스 | 세부내용 | |
|---|---|---|---|
|
|
|
|
|
| M앱이 설치되지 않은 경우 → M앱의 설치를 유도 | |
| M앱이 마이그레이션을 지원하지 않는 버전 → M앱의 업데이트를 유도 | ||
| 버즈스크린을 활성화하는데 필요한 정보가 충분하지 않은 경우 → M앱의 잠금화면 활성화 페이지로 이동 | ||
| 잘못된 연동 혹은 일시적인 에러로 발생
| ||
| - |
| |
checkAvailability Error Flow
Advanced Usage
M앱과 L앱 간의 통신 유틸
마이그레이션 SDK에서 제공하는 기능 이외에도 M앱과 L앱 간의 통신이 필요하다면 여기서 제공하는 통신 모듈을 사용하여 개발할 수 있습니다. 자세한 내용은 통신 유틸리티archived 문서를 참고해주세요.
Appendix
간단한 방법으로 L앱 빌드하기
sample_lock_light에서 확인할 수 있는 샘플 잠금화면 앱은 위 가이드의 구현을 담았을 뿐만 아니라 최소한의 기능도 구현되어있습니다. 따라서 sample_lock_light 을 다운받고 다음 과정만 진행해도 잠금화면 앱이 완성됩니다.
기능 구현
build.gradle변경 :my_app_key는 기존에 발급받았던 버즈스크린 앱키로 변경하고,applicationId는 새롭게 만드는 잠금화면 앱의 패키지명으로 변경합니다.BuzzScreen.init()에서 사용되는appKey를 신규 값으로 변경합니다.AndroidManifest.xml변경 :<app_license>를 새롭게 발급받은 값으로 변경합니다.M앱 잠금화면 활성화 페이지 딥링크 설정 :
App.java파일 내의DEEP_LINK_ONBOARDING를 M앱 잠금화면 활성화 화면 딥링크로 설정합니다.
디자인 변경
아이콘 :
ic_launcher.png변경색상 :
res/colors.xml변경만으로 메인 색상 적용 가능로고 :
activity_main.xml에서 툴바의 로고 변경
이 외의 잠금화면 UI 및 기능 커스텀은 고급 설정 문서를 참고해주세요.