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.

An extension SDK that helps you to work with the BuzzScreen SDK which shows personalized content and ads on your Android lockscreen.
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 BuzzScreen SDK Basic Usage .
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 BuzzScreen Migration SDK Usage .

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

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.

Before initiating the integration process, consultation with Buzzvil BD Team in advance is mandatory.

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.bintray.com/buzzvil/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

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

If you already have user information for gender and age, use the methods as above. If you do not have those user information, you can also set user info in L app. Note that if you do not set age and gender information, ads with targeted info will not be allocated, which will reduce the total number of ads users can see.

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 `userId` can updated through re-install or by certain period, you MUST discuss it with your account manager in advance. 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. `sync()` must be called with user information set-up methods as sample code below `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
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. Be sure to call up the code to set User Information described above. L app uses this information to activate the lockscreen.
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

BuzzScreen SDK must be integrated to use the personalization feature in BuzzScreen. This guide explains the integration of BuzzScreenClient and BuzzScreen SDK at the same time for your understanding. If you only want to see the BuzzScreen SDK integration separately, see BuzzScreen SDK Basic Usage doc.

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.

Reward API: Publisher API server that will actually process the request and provide rewards for the user. For more information, please refer to Reward Accumulation Postback API doc.

	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

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

Otherwise you might get compile errors such as com.android.dex.DexException. If you encounter any errors, please do not hesitate to contact your account manager.

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)

Latest 15.0.1 version is recommended.

Basic Usage

1. Configuration

1) Modify `build.gradle` inside your module.

General

android {
    defaultConfig {
        // Please replace my_app_key with the app key given for BuzzScreen integration process
        manifestPlaceholders = [buzzScreenAppKey:"my_app_key"]
    }
}

...

repositories {
    maven { url "https://dl.bintray.com/buzzvil/maven/" }
}

BuzzScreen Integration

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

BuzzScreenClient Integration

dependencies {
    implementation 'com.google.android.gms:play-services-base:16.0.1'
    implementation 'com.google.android.gms:play-services-ads:15.0.1'
    implementation 'com.google.android.gms:play-services-location:16.0.0'

    // BuzzScreenClient library for L app. The version MUST be same as BuzzScreenHost's
    implementation 'com.buzzvil.buzzscreen.ext:buzzscreen-client:1.4.0' {
        exclude group: 'com.buzzvil', module: 'buzzscreen'
    }


    // (optional) Library for encryption provided by Extension SDK
    // implementation 'com.github.joshjdevl.libsodiumjni:libsodium-jni-aar:1.0.8'
}

2) Modify `AndroidManifest.xml`

<manifest>
    <application>
        ...
        <!-- Configuration for BuzzScreen-->
        <!-- app_license meta-data is unnecessary for BuzzScreen SDK version 1.9.5.6 or higher -->
        <meta-data
            android:name="app_license"
            android:value="<app_license>" />
        
        <!-- plist meta-data is unnecessary for BuzzScreen SDK version 1.9.0.7 or higher -->
        <meta-data
            android:name="com.buzzvil.locker.mediation.baidu.plist"
            android:value="<plist>" />
    </application>
</manifest>

Please ask your account manager for <app_license> and <plist>. But, these are unnecessary for BuzzScreen SDK version 1.9.5.6 or higher

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
Initializing BuzzScreen REQUIRED	`BuzzScreen.init(String appKey, Context context, Class<?> lockerActivityClass, int imageResourceIdOnFail)` Place this code in the `onCreate()` in your application class. You MUST call this method prior to any other method calls of the Buzzscreen SDK.	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 UI Customization . `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. If it is the first time to create application class in your app, please do not forget to register application class in `AndroidManifest.xml`.
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

Initializing BuzzScreenClient

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        ...
        // app_key : app key for SDK usage, check in your admin
        // SimpleLockerActivity.class : Activity class of the lockscreen
        // R.drawable.image_on_fail : An image that will be shown if there is no network error or temporarily no campaigns to show on the lockscreen.
        BuzzScreen.init("app_key", this, SimpleLockerActivity.class, R.drawable.image_on_fail);

        // Initialization for BuzzScreenClient
        // The example code uses com.buzzvil.buzzscreen.sample_host for M app package name.
        BuzzScreenClient.init(this, "com.buzzvil.buzzscreen.sample_host");        
        
        // Optional
        BuzzScreenClient.setHostEventListener(new BuzzScreenClient.HostEventListener() {
          @Override
          public void onLogout() {
            // When logout is called from M app
          }
        });
        
        // Optional
        BuzzScreenClient.setOnDeactivatedByHostListener(new BuzzScreenClient.OnDeactivatedByHostListener() {
          @Override
          public void onDeactivated() {
            // when L app lockscreen is disabled by M app.
          }
        });
    }
}

Launching BuzzScreen

public class StartActivity extends AppCompatActivity {    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_start);
        
        // Adds this method to the activity that is executed first when the L app launches.
        BuzzScreen.getInstance().launch();
    }
}

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.

If M app has set all age and gender information, skip this section.

If you do not set age and gender information anywhere in M app or L app, ads with targeted will not be allocated, which will reduce the total number of ads users can see.

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. This is the `UserProfile` of the BuzzScreen SDK in the L app, not the BuzzScreenClient.
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`.

// get UserProfile from BuzzScreen
UserProfile userProfile = BuzzScreen.getInstance().getUserProfile();

// Update BuzzScreen UserProfile
userProfile.setBirthYear(newBirthYear);
userProfile.setGender(newGender);

// Optional : use this method when you need to pass a changed UserProfile to BuzzScreenHost.
BuzzScreenClient.requestUserProfileSync(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

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.

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);
        
        // This example assumes that MainActivity is the start activity and adds the launch method here:
        BuzzScreen.getInstance().launch();
    }
        
    @Override
    protected void onResume() {
        super.onResume();
        buzzScreenClient.checkAvailability(new BuzzScreenClient.OnCheckAvailabilityListener() {
            @Override
            public void onAvailable() {
                // Called when the buzz screen can be activated.
                // Configure the flow required here to activate the lockscreen.
                // Final lockscreen activation works via BuzzScreen.getInstance().activate().
            }

            @Override
            public void onError(BuzzScreenClient.CheckAvailabilityError error) {
                switch (error) {
                    case HOST_APP_NOT_INSTALLED:
                        sendToPlayStore("App is not installed.\nMove to installation link.");
                        break;
                    case HOST_NOT_SUPPORTED_VERSION:
                        sendToPlayStore("App is not the latest version.\nMove to installation link.");
                        break;
                    case NOT_ENOUGH_USER_INFO:
                        // Gather user information and usage agreement via M app.
                        sendToMain();
                        break;
                    case UNKNOWN_ERROR:
                        Toast.makeText(MainActivity.this, "Error. Please retry.", Toast.LENGTH_SHORT).show();
                        break;
                }
            }
        });
    }
    
    @Override
    public void onPause() {
        super.onPause();
        // Call to pause checkAvailability.
        // onAvailable or onError is called unless stop here.
        buzzScreenClient.pause();    
    }
}

`checkAvailability` and activation flow from L app

For more information on lockscreen activation, refer to this page.

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 Reward Accumulation Postback API doc.

If you would like to send the user a push notification on point accumulation, it should be processed/sent from your server after receiving a reward accumulation request from BuzzScreen.

Appendix

1. Advanced Usage

If you need any of the following features, please refer to Advanced Usage :
- 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 Custom Targeting.
To customize lockscreen service notification, please refer to Lockscreen Service Notification.

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.

This extension helps the user information of M app to be used in L app. Actual lockscreen is driven by BuzzScreen SDK which is separate SDK from this extension. If you would like to see the BuzzScreen SDK guide separately, see BuzzScreen SDK Basic Usage.

You can try the sample app through the following steps.

Clone or download the entire project from GitHub. Unzip it.
Import unzipped directory from Android Studio 3 or more (File>New>Import Project)
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.
Now you can select and build the modules.

BuzzScreen Extension SDK Usage

Introduction

1) BuzzScreen SDK & BuzzScreen Extension SDK Work Flow

2) Requirements

BuzzScreenHost integration in M app

Basic Usage

1. Modify build.gradle

2. Add necessary codes to Application Class

Sample Code

3. User information setting and synchronization

4. Controlling L app lockscreen

L App Lockscreen Activation Flow

BuzzScreenClient integration in L app

Prerequisites

Requirements

Basic Usage

1. Configuration

1) Modify build.gradle inside your module.

General

BuzzScreen Integration

BuzzScreenClient Integration

2) Modify AndroidManifest.xml

2. Call Methods

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

Sample Code

2) User information setting

3) Lockscreen Activation and integrating user information

checkAvailability and activation flow from L app

Reward Accumulation - Server to Server Integration

Appendix

1. Advanced Usage

2. Creating market-ready L app using sample

1. Modify `build.gradle`

1) Modify `build.gradle` inside your module.

2) Modify `AndroidManifest.xml`

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

`checkAvailability` and activation flow from L app