Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 21 Next »

개요

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 연동 가이드를 참고하세요.

앱 재설치 또는 일정 주기에 따라 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 이상에서 사용 가능합니다.

    • 암호화하고자 하는 경우 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앱의 잠금화면을 활성화합니다.

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

설정하지 않을 경우 컴파일 시에 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를 추가하세요.

버즈스크린 연동

dependencies {
    implementation 'com.buzzvil:buzzscreen:4.15.+'
}

L앱을 위한 BuzzScreenClient 라이브러리

dependencies {
    // L앱을 위한 BuzzScreenClient 라이브러리. BuzzScreenHost 와 버전이 반드시 일치해야 합니다.
    implementation 'com.buzzvil.buzzscreen.ext:buzzscreen-client:1.8.+'

    // (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앱의 초기화 필수

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

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

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

 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 을 통해 형식에 맞추어 성별 설정

  • UserProfile.USER_GENDER_MALE : 남성

  • UserProfile.USER_GENDER_FEMALE : 여성

유저 정보 동기화 선택

BuzzScreenClient.requestUserProfileSync(boolean encrypt)

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

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

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

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

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

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

항목

코드 & 호출 위치

설명

앱 위에 표시 권한 획득

BuzzScreen.getInstance().showOverlayPermissionGuideDialogIfNeeded(OverlayPermissionListener listener)

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

L앱에서는 M앱에서도 잠금화면 활성화 호출이 가능하므로, 이 권한 획득을 SplashActivity 등 앱 실행 시 나타나는 첫 화면, 즉 가장 빠른 시점에 필수적으로 받고, 권한 획득이 안 된 경우에는 앱 사용을 할 수 없게 종료하는 등의 구현을 권장합니다.

버즈스크린 활성화에 필요한 유저정보 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()

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

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

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와 잠금화면 활성화 흐름

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는 바꾸어서 사용해도 됩니다.

BuzzScreenHost.getDataStorage().put("SHARED_CONFIG_KEY", "config_value");

// Synchronous
String value = BuzzScreenClient.getDataStorage().get("SHARED_CONFIG_KEY");
// Asynchronous
BuzzScreenClient.getDataStorage().getAsync("SHARED_CONFIG_KEY", new DataStorage.AsyncQueryListener() {
    @Override
    public void onQueryComplete(String value) {
    }
});

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는 바꾸어서 사용해도 됩니다.

// Sender
Bundle eventData = new Bundle();
eventData.putString("extra_info", "extra_value");
BuzzScreenHost.getEventHandler().post("SAMPLE_EVENT", eventData);

// Receiver
BuzzScreenClient.getEventHandler().registerEventListener("SAMPLE_EVENT", new EventHandler.OnEventListener() {
    @Override
    public void onEvent(Bundle extras) {
        Log.d(TAG, "onReceive SAMPLE_EVENT");
        String extraInfo = extras.getString("extra_info"); // "extra_value" returned
        ...
    }
});

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는 바꾸어서 사용해도 됩니다.

// Server
BuzzScreenHost.getRequestHandler().registerResponder(1000, new MsgRequestHandler.Responder() {
    @Override
    public Bundle respond(Bundle parameters) {
        Bundle response = new Bundle();
        response.putString("response_key", "response_sample");
        return response;
    }
});

// Client
BuzzScreenClient.getRequestHandler().request(1000, null, new Request.OnResponseListener() {
    @Override
    public void onResponse(Bundle response) {
        String value = response.getString("response_key"); // "response_sample" returned
        ...
    }

    @Override
    public void onFail(Request.FailReason failReason) {
    }
});

  • No labels