BuzzScreen Extension SDK Usage

Introduction

Please refer to the sample included in the SDK before applying to your app. - M app / L app

  • "M app" indicates the publisher app with the sign-in feature feature.

  • "L app" indicates the new lockscreen-exclusive application hereinafter.

  1. An extension SDK that helps you to work with the BuzzScreen SDK which shows personalized content and ads on your Android lockscreen.

  2. You need user information to use the personalization feature in BuzzScreen, and you need to pass user information to the M app in one of two ways:

    1. Implement sign-in feature for lockscreen-exclusive applications - refer to https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/392462350 .

    2. If you can't implement sign-in feature for lockscreen-exclusive application, integrate BuzzScreen Extension SDK to use your existing user information of publisher app - see the current guide

Unless you are new to BuzzScreen SDK, that is, if you have already integrated BuzzScreen SDK in your publisher app, please refer to https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/402948097 .

1) BuzzScreen SDK & BuzzScreen Extension SDK Work Flow

  • Necessary SDK’s to integrate

    • M app: BuzzScreenHost SDK

    • L app: BuzzScreenClient SDK + BuzzScreen SDK

2) Requirements

Content

Detail

Content

Detail

1

Android version

Requires 4.0.3 (API level 15) or newer.

2

APK signature

As M app and L app sync data via BuzzScreenHost SDK and BuzzScreenClient SDK, the two APKs should be signed with an identical signature to block access from other apps.

Using protectionLevel="signature" is recommended.

3

Buzzvil’s Check

Apk files of both M app and L app fully integrated following the guide should be passed on to Buzzvil BD team so they can be reviewed BEFORE uploading on the market.

 


BuzzScreenHost integration in M app

Basic Usage

  • BuzzScreenHost, which is integrated in the M app, provides user information necessary to activate the lockscreen of the L app.

    • If you can not provide the required information from the M app, the lockscreen in L app can not be activated.

  • The L app should check the status of the M app at runtime to determine if the lockscreen of the L app can be activated.

    • When the M app is uninstalled, the lockscreen in the L app is automatically deactivated. All other lockscreen management responsibilities are entirely in the L app.

1. Modify build.gradle

Add manifestPlaceholders.

android { defaultConfig { // Please replace my_app_key with the app key provided for BuzzScreen integration process. manifestPlaceholders = [buzzScreenAppKey:"my_app_key"] } } ... repositories { maven { url "https://dl.buzzvil.com/public/maven" } } ... dependencies { // Extension library for M app. Please take extra caution of the library name as it is different for L app. implementation 'com.buzzvil.buzzscreen.ext:buzzscreen-host:1.4.0' // (optional) Library for encryption provided by Extension SDK // implementation 'com.github.joshjdevl.libsodiumjni:libsodium-jni-aar:1.0.8' }

 

2. Add necessary codes to Application Class

Content

Method

Place

Detail

Content

Method

Place

Detail

Initialization code of M app for BuzzScreenHost

BuzzScreenHost.init(Application application, String clientPackageName)

Call in Application class.

Parameters

  • Application : pass this for Application.

  • clientPackageName : L App Package name

Sample Code

public class App extends Application { @Override public void onCreate() { super.onCreate(); // Initialization for BuzzScreenHost // example code uses com.buzzvil.buzzscreen.sample_client for L app package name. BuzzScreenHost.init(this, "com.buzzvil.buzzscreen.sample_client"); Example of registering listener called when Buzzscreen is activated in L app, deactivating that of M app // Optional // Example of registering listener called when Buzzscreen is activated/deactivated in L app, or user information of L app is changed BuzzScreenHost.setClientEventListener(new BuzzScreenHost.ClientEventListener() { @Override public void onActivated() { // called when Buzzscreen is activated in L app Log.i("MainApp", "ClientEventListener - onActivated"); } @Override public void onDeactivated() { // called when Buzzscreen is deactivated in L app Log.i("MainApp", "ClientEventListener - onDeactivated"); } @Override public void onUserProfileUpdated(UserProfile userProfile) { // called when user information of L app is changed Log.i("MainApp", "ClientEventListener - onUserProfileUpdated"); } }); } }

 

3. User information setting and synchronization

Content

Method

Place

Detail

Content

Method

Place

Detail

Class for setting user profile

BuzzScreenHost.getUserProfile()

Should be set before activating L app lockscreen

You can get UserProfile by calling this method.

Set User Id required

setUserId(String userId)

  • You must call setUserId() in order for the BuzzScreen SDK to behave correctly.

  • userId is a unique value by which publishers can identify each user.

  • This value will be passed back to your server in a postback when there's a reward accumulation event.

If the user ID is not set, the L app determines that the user is not signed in from the M app and you will get a NOT_ENOUGH_USER_INFO error.

User Age recommended

setBirthYear(int birthYear)

Set age by Year of Birth of the user in 4 digits (e.g, 1988)

User Gender recommended

setGender(String gender)

Set gender by using predefined string constants below:

  • UserProfile.USER_GENDER_MALE : For male

  • UserProfile.USER_GENDER_FEMALE : For female

User info Synchronizationrequired

sync(boolean encrypt)

Synchronize the user information with L app.

  • encrypt optional : An optional parameter to encrypt userProfile when synchronizing user info with L app.

    • Available from v1.0.2.0 and above

    • To encrypt userProfile info, pass true for encrypt.

 

BuzzScreenHost.getUserProfile() .setUserId(newUserId) .setBirthYear(newBirthYear) .setGender(newGender) .sync(encrypt);

 

4. Controlling L app lockscreen

Content

Method

Detail

Content

Method

Detail

Sign out required

BuzzScreenHost.logout()

Call BuzzScreenHost.logout() when a user becomes unqualified to use lockscreen, such as signing out from M app.

  • Deactivate lockscreen in L app

  • Reset user information from M app and L app

Launch L app recommended

BuzzScreenHost.launchClient()

Launch the L app.

  • If the L app is installed, the L app will be launched.

  • If the L app is not installed, it will be launched automatically after installation through market.

Check if L app lockscreen is activated optional

BuzzScreenHost.isClientActivated()

Returns true if lockscreen is activated in L app, and false if deactivated.

Activate L app lockscreen optional

BuzzScreenHost.requestActivation(OnRequestActivateResponseListener listener, boolean encrypt)

Activates lockscreen in L app. When activating lockscreen, user info set in the M app will be used.

Parameters

  • OnRequestActivateResponseListener

    • onAlreadyActivated() : This method will be called if BuzzScreen was already enabled in L app.

    • onActivated() : This method will be called when BuzzScreen is enabled in L app.

    • onError(RequestActivationError error) : This method will be called when BuzzScreen of L app activation fails.

      • CLIENT_APP_NOT_INSTALLED : Error code indicating when activation fails because L app is not installed

      • CLIENT_NOT_SUPPORTED_VERSION : Error code indicating when the activation fails because the L App doesn't support BuzzScreenClient features

      • NOT_ENOUGH_USER_INFO : Error code indicating when UserProfile is missing essential userId

      • UNKNOWN_ERROR : Error code indicating incorrect integration or temporary error

  • encrypt optional : An optional parameter to encrypt userProfile when activating lockscreen in L app.

    • Available from v1.0.2.0 and above

    • To encrypt userProfile info, pass true for encrypt.

Deactivate L app lockscreen optional

BuzzScreenHost.requestDeactivation()

Deactivates lockscreen in L app. ​

L App Lockscreen Activation Flow

 

 


 

BuzzScreenClient integration in L app

  • Below are the key values necessary for the integration:

    • app_key : Please find the app_key on your BuzzScreen dashboard. Please ask your account manager if the account details are not provided yet. (Required in the build.gradle and BuzzScreen.init method)

    • app_license : Please ask your account manager. (Required in the AndroidManifest.xml setting)

    • plist : Please ask your account manager. (Required in the AndroidManifest.xml setting)

  • It is required to submit the integrated APK file to your account manager for review before going live.

Prerequisites

The following API server should be prepared for the service of lockscreen application.

Content

Detail

Content

Detail

1

Setting User Profile

If you set up user targeting information such as gender and age in BuzzScreenHost of M app, you do not have to set it from L app. But if you have not set it up, you can request the information to user in the L app, and set User information.

2

Activation / Deactivation

  • The L app can activate the lockscreen by obtaining the necessary information from the M app.

  • If you call BuzzScreenHost.logout() at the time when user signed out of the M app, or if the M app is removed or the data of the M app is erased, the lockscreen of the L app is automatically disabled.

Requirements

Content

Detail

Content

Detail

1

Android version

Requires 4.0.3 (API level 15) or newer.

2

Match Google Play Services version no.

Please change the version number in Google Play Services libraries below to match the version number of Google Play Services in your app.

  • com.google.android.gms:play-services-base

  • com.google.android.gms:play-services-ads

  • com.google.android.gms:play-services-location

3

If app’s support library version is 26 or higher

You need to upgrade play service version to 12 or higher due to the instability of GCM(Google Cloud Messaging)


Basic Usage

1. Configuration

1) Modify build.gradle inside your module.

General
BuzzScreen Integration

BuzzScreenClient Integration

 

2) Modify AndroidManifest.xml

2. Call Methods

In order to integrate BuzzScreen into Android apps, please follow the 3 steps below: ​ 1) Initialization → 2) Set User Profile → 3) Turn on/off the lockscreen

Also, please initialize BuzzScreenClient together in step 1) to synchronize user information with M app.

1) Initialization : call init() and launch()

Content

Method & Place

Detail

Content

Method & Place

Detail

Initializing BuzzScreen required

BuzzScreen.init(String appKey, Context context, Class<?> lockerActivityClass, int imageResourceIdOnFail)

  • Place this code in the onCreate() in your application class.

Parameters

  • appKey : Please find the app_key on your BuzzScreen dashboard.

  • context : The application context (you can simply use this)

  • lockerActivityClass : A lockscreen activity class.

    • You can simply use SimpleLockerActivity.class which is already provided in the SDK.

    • You can also implement your own lockscreen activity class to suit unique needs of yours, by subclassing BaseLockerActivity.class. Please refer to .

  • imageResourceIdOnFail : An image file to be displayed when either network error occurs or there is no campaign available temporarily.

    • Include the file as resource inside the app. Use the resource id of the image.

Initialization code of BuzzScreenClient for L app required

BuzzScreenClient.init(Application application, String hostPackageName)

  • Place: Call it after BuzzScreen.init.

Parameters

  • application : pass the Application with this.

  • hostPackageName : M App Package name

Listener for deactivation request from M app required

BuzzScreenClient.setOnDeactivatedByHostListener(OnDeactivatedByHostListener listener)

  • This method registers a listener that is called when the lockscreen of L app is disabled by calling of BuzzScreenHost.requestDeactivation() from M app or deleting M app.

Parameters

  • OnDeactivatedByHostListener

    • onDeactivated : Called when lockscreen of L app is disabled

Launch BuzzScreen required

BuzzScreen.getInstance().launch()

  • Place: Adds this method to the activity that is executed first when the L app launches.

 

Sample Code

 

2) User information setting

If you do not set User information of gender and age in the BuzzScreenHost of M app, you can set targeting information here.

Content

Method

Detail

Content

Method

Detail

Object for setting user profile information

BuzzScreen.getInstance().getUserProfile()

You can set user profile information in this Class.

  • Ad campaigns will be targeted to specific demo by using user’s age and gender information.

User Age recommended

setBirthYear(int birthYear)

Set age by Year of Birth of the user in 4 digits (e.g. 1988)

User Gender recommended

setGender(String gender)

Set gender by using predefined string constants below:

  • UserProfile.USER_GENDER_MALE : For male

  • UserProfile.USER_GENDER_FEMALE : For female

User Profile Synchronization optional

BuzzScreenClient.requestUserProfileSync(boolean encrypt)

Use this method when you need to pass a changed UserProfile to BuzzScreenHost.

  • encrypt optional : An optional parameter to encrypt UserProfile when synchronizing user info with M app.

    • Available from v1.0.2.0 and above

    • To encrypt UserProfile info, pass true for encrypt.

 

3) Lockscreen Activation and integrating user information

Lockscreen activation on L app works as follows: Information transfer from M app → BuzzScreen Activation.

To get data transferred from M app, BuzzScreenClient provides the following function.

Content

Method & Place

Detail

Content

Method & Place

Detail

Obtaining user info from M app required

checkAvailability(OnCheckAvailabilityListener listener, boolean encrypt)

  • Place: Put this in onResume on the first activity of L app so that this is called everytime L app launches.

This method is used to obtain data needed for BuzzScreen activation from M app asynchronously.

Parameters

  • OnCheckAvailabilityListener

    • onAvailable() : Called when BuzzScreen can be activated.

    • onError(CheckAvailabilityError error) : Called when BuzzScreen cannot be activated.

      • HOST_APP_NOT_INSTALLED

        • M app is not installed. → In this case, redirect users to M app install process.

      • HOST_NOT_SUPPORTED_VERSION

        • Current M app version doesn't support BuzzScreenHost features. → In this case, redirect users to update M app version.

      • NOT_ENOUGH_USER_INFO

        • This is returned when user information are not enough for BuzzScreen activation. → Users should be redirected to sign in page on M app.

      • UNKNOWN_ERROR : Wrong integration or temporary error. In case of temporary error, lead to retry.

        • For buzzscreen-client 1.0.1 or higher, it is necessary to add a button to allow users to deactivate BuzzScreen in case UNKNOWN_ERRORoccurs .

  • encrypt optional : An optional parameter to encrypt UserProfile when obtaining user info from M app.

    • Available from v1.0.2.0 and above

    • To encrypt UserProfile info, pass true for encrypt.

Activating BuzzScreen required

BuzzScreen.getInstance().activate()

Turn on BuzzScreen.

  • activate() doesn't need to be called repeatedly unless deactivate() is called. BuzzScreen will be kept activated once activate() is called and lockscreen cycle will be managed automatically since then.

Deactivating BuzzScreen required

BuzzScreen.getInstance().deactivate()

Turn off BuzzScreen.

 

checkAvailability and activation flow from L app

 

 

Reward Accumulation - Server to Server Integration

  • When a reward accumulation event occurs from a user, BuzzScreen does not handle this in the client side. Instead the BuzzScreen server will make a reward accumulation request to the publisher's server and the publisher's server should process the request and provide rewards for the user.

  • Regarding implementing the postback, please refer to doc.

 


Appendix

1. Advanced Usage

  • If you need any of the following features, please refer to :

    • Customized lockscreen, slider UI, clock UI, or extra lockscreen widgets.

    • Separating the lockscreen process from main process for efficient memory usage.

  • To enable customized targeting features, please refer to .

  • To customize lockscreen service notification, please refer to .

 

2. Creating market-ready L app using sample

Once you have integrated each SDK to M app and L app, you can sync the user information set in the M app with L app and use it in L app's BuzzScreen.

You can try the sample app through the following steps.

  1. Clone or download the entire project from GitHub. Unzip it.

  2. Import unzipped directory from Android Studio 3 or more (File>New>Import Project)

  3. Replace android: value = "<app_license>", android: value = "<plist>" in AndroidManifest.xml for each module. If you want to build only the sample apps without values, you can empty the value as "". Re-sync Gradle project.

  4. Now you can select and build the modules.