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

Introduction

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

Also, 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.

This guide is aimed to migrate lockscreen users of an app integrated with the existing BuzzScreen SDK to the new lockscreen-exclusive application, in order to be in compliance with the new Google Play policy regarding lockscreen monetization.

Definition of Terms
- "M app" indicates the existing application integrated with BuzzScreen.
- "L app" indicates the new lockscreen-exclusive application hereinafter.
Summary: This guide explains a migration method with minimal cost by utilizing M app's existing features and BuzzScreen integration.
- Use case: Recommended when an independent L app with its own login system cannot be provided - in this case L app may log in its users via M app login system.
  - SDK provides communication methods from M app to L app that is used to transfer user info(user id, age, gender) and lockscreen activation status.
- Security: As M app and L app exchange data for migration, the two APKs should be signed with an identical signature to block access from other apps. Using protectionLevel="signature" is recommended.
- cf) Installation of L app (download & installation of the APK file from Google Play) can only be done with the user's action, thus cannot be automated.
Through the integration process of this SDK, all processes except the installation of L app can be automated, seamlessly migrating M app BuzzScreen users to L app BuzzScreen.

Migration SDK Workflow

- 1.1 Introduction
2 M App Migration Implementation
- 2.1 Basic Usage
- 2.2 Advanced Usage
3 L App Migration Implementation
- 3.1 Basic Usage
- 3.2 Advanced Usage
- 3.3 Appendix

M App Migration Implementation

Basic Usage

M app provides necessary data required to activate lockscreen in L app, even after migration is finished the first time.
- If M app is unable to provide the data, lockscreen cannot be activated in L app. In this case, users should be directed to a lockscreen activation page on M app.
- This process is done through “Lockscreen Opt-in page modification” step.
Every time L app is launched, it checks the status of M app and determines if lockscreen can be activated on L app.
- When M app is removed, lockscreen from L app is automatically deactivated.

1. Modify `build.gradle`

1) Add `manifestPlaceholders`

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

2) Add the followings to `dependencies`

Migration library for M app should be added, and BuzzScreen SDK version must be updated to 1.6.3 or higher.

No additional process is required if the BuzzScreen SDK version is 1.+ as it is automatically updated, but it is necessary to set the version as 1.6.3 or higher if the version is explicitly specified.

BuzzScreen Integration as before

Migration library for M app

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

...

dependencies {
    // Please take extra caution of the library name as it is different for L app. 
    implementation 'com.buzzvil.buzzscreen.ext:migration-host:1.4.0' {
        exclude group: 'com.buzzvil', module: 'buzzscreen'
    }

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

2. Add necessary codes to Application Class

Call MigrationHost.init, following BuzzScreen.init added for the existing BuzzScreen integration.

MigrationHost.init(Context context, String lockScreenPackageName) : Initialization code of M app for migration
- Parameters
  - context : pass this for Application context.
  - lockScreenPackageName : L App Package name
- Example
  public class App extends Application { @Override public void onCreate() { super.onCreate(); // Existing code to initialize Buzzscreen BuzzScreen.init("app_key", this, SimpleLockerActivity.class, R.drawable.image_on_fail); // Initialization for migration // example code uses com.buzzvil.buzzscreen.sample_lock_light for L app package name. MigrationHost.init(this, "com.buzzvil.buzzscreen.sample_lock_light"); // Example of registering listener called when Buzzscreen is activated in L app, deactivating that of M app MigrationHost.setOnDeactivatedByLockScreenAppListener(new MigrationHost.OnDeactivateByLockScreenAppListener() { @Override public void onDeactivated() { Log.i("MainApp", "LockScreen is deactivated by LockScreen App"); } }); } }

3. Lockscreen Opt-in page modification

L app doesn't contain any process to directly receive user profile data or usage agreement from the users in the app; it can only activate the lockscreen with user info input from M app. Thus, L app uses the lockscreen opt-in page (user profile, usage agreement, opt-in/out setting) in the existing lockscreen opt-in page of M app.

	Content	Method	Detail

Content

Method

Detail

1

Set up a deeplink redirecting to lockscreen opt-in activity

-

If L app requires necessary data or usage agreement for lockscreen activation, it redirects users to the opt-in page of M app.
If the deeplink does not exist, it leads to the main activity of M app.

2

Activate L app BuzzScreen

MigrationHost.requestActivationWithLaunch()

This method activates the lockscreen through L app. If L app is installed, L app lockscreen will be automatically activated; if not, users will be redirected to Google Play Store to download and install L app prior to automatically activating lockscreen.

Before calling MigrationHost.requestActivationWithLaunch(), code for User info setting should be called in advance using BuzzScreen.getInstance().getUserProfile(). L app utilizes the exact same info to activate lockscreen.

Modify the opt-in/out switch in lockscreen opt-in page of M app to a banner form. When a user clicks the banner or other buttons that activate lockscreen after receiving usage agreement (same as where BuzzScreen.getInstance().activate() is called), call the following function.
- The banners act as a migration channel for existing users as well as an acquisition channel of L app targeting new users who haven't used the lockscreen before.

L app lockscreen activation process

4. Sign out process

Call following two methods below when a user signs out from M app.

The purpose is to deactivate lockscreen in L app and for L app to receive new user information from M app when activating lockscreen afterwards.

BuzzScreen.getInstance().logout() : Deactivate lockscreen in M app and reset user information.
MigrationHost.requestDeactivation() : If lockscreen is activated in L app, deactivate the lockscreen.

+. Remove codes for BuzzScreen opt-in/out optional

Remove both BuzzScreen.getInstance().activate() and BuzzScreen.getInstance().deactivate() inserted for lockscreen opt-in/out. However, if lockscreen opt-out is provided on the lockscreen, DO KEEP BuzzScreen.getInstance().deactivate() call in this block.

Advanced Usage

Other useful methods

Content	Method	Detail

Content	Method	Detail
Check if L app lockscreen is activated	`MigrationHost.isLockScreenAppActivated()`	Returns `true` if lockscreen is activated in L app, Returns `false` if deactivated.
Sync user info when it’s updated in M app	`MigrationHost.requestUserProfileSync(boolean encrypt)`	If user id is periodically updated in the existing M app, call the method above after calling `setUserId(String string)` in order to synchronize user info in L app with the updated info. If the method above isn't called, the updated user information is not applied until `checkAvailability` is called henceforth in L app. `encrypt` optional : An optional parameter to encrypt `UserProfile` when synchronizing user info with L app. To encrypt `UserProfile` info, pass `true` for `encrypt`. (Available from v1.0.2.0 and above)
Customize market link for L app	`MigrationHost.setLockScreenAppMarketLink(String link)` The method above should be called prior to `requestActivationWithLaunch()`.	When L app is installed through `requestActivationWithLaunch()`, use the method above if you'd like set a custom link for acquisition channel tracking, rather than a default market uri with the package name. Parameters `link` : custom link
Activate L app lockscreen without running L app	`MigrationHost.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. `LOCKSCREEN_APP_NOT_INSTALLED` : Error code indicating when activation fails because L app is not installed `LOCKSCREEN_APP_MIGRATION_NOT_SUPPORTED` : Error code indicating when the activation fails because the L App doesn't support migration features. `UNKNOWN_ERROR` : Error code indicating incorrect integration or temporary error `encrypt` optional : An optional parameter to encrypt `UserProfile` when activating lockscreen in L app. To encrypt `UserProfile` info, pass `true` for `encrypt`. (Available from v1.0.2.0 and above)

L App Migration Implementation

	Content	Detail

	Content	Detail
1	User Profile setting and Usage Agreement	User profile setting flow inside the L app is not required for L app lockscreen integration. User info transferred from M app via the migration SDK is automatically used. L app is capable of activating a lockscreen using user information and usage agreement gathered from M app. Users who have been using M app lockscreen are considered to have already agreed with using the lockscreen.
2	Activation / Deactivation	When required information are missing, users will be notified to activate the lockscreen on M app’s lockscreen activation page. Deep-linking to M app Lockscreen Activation Page would help implement a user-friendly experience. L app lockscreen will be automatically deactivated when either `MigrationHost.requestDeactivation()` is called on M app at logout or M app is removed.
3	Building L app	You can easily build L app with sample source. (Refer to the Appendix below.) For additional communication between M app and L app, you can utilize https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/403406895 . Through the utils, you can utilize feature or data from M app in L app.

Basic Usage

1. Modify `build.gradle`

1) Add `manifestPlaceholders`

2) Add the followings to `dependencies`

Add the BuzzScreen library as well as the L app migration library. It requires BuzzScreen ver 1.6.3 or higher.

BuzzScreen Integration

Migration library for L app

2. Modify `AndroidManifest.xml`

Renewed app_license should be used and applied on L app in order to integrate BuzzScreen.

3. Add necessary codes to Application Class

Call Buzzscreen.init for BuzzScreen integration and MigrationClient.init for migration in that order.

Content	Method & Place	Detail

Content

Method & Place

Detail

Initialization code of L app for migration required

MigrationClient.init(Context context, String mainPackageName)

Parameters

context : pass the Application context with this.
mainPackageName : M App Package name

Registering listener called when lockscreen of L app is deactivated required

MigrationClient.setOnDeactivatedByMainAppListener(OnDeactivatedByMainAppListener listener)

This method registers a listener that is called when lockscreen on L app is disabled either when

MigrationHost.requestDeactivation() is called from M app
or M app is removed.

Parameters

OnDeactivatedByMainAppListener
- onDeactivated : Called when L app lockscreen is disabled

4. Lockscreen Activation and Migration

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

Migration starts with the above process when L app launches, and L app's lockscreen is activated using M app's user information henceforth.
Once L app lockscreen is activated, M app lockscreen is deactivated.

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

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, and activate the lockscreen automatically depending on M app status.
  - Condition for automatic lockscreen activation
    1. Either M app lockscreen is being used
    2. Or activating L app by calling MigrationHost.requestActivationWithLaunch()

Parameter	Response	Detail

Parameter	Response	Detail
`OnCheckAvailabilityListener`required	`onAvailable(boolean autoActivated)` Called when BuzzScreen can be activated. When lockscreen is activated via `onAvailable`, please refer to “L app lockscreen activation process” diagram above.	`onAvailable(boolean autoActivated)`	`autoActivated` `true` when lockscreen is automatically activated `false`otherwise
	`onError(AvailabilityCheckError error)` Called when BuzzScreen cannot be activated. Refer the following image for handling `onError`	`MAIN_APP_NOT_INSTALLED`	M app is not installed. → In this case, redirect users to M app install process.
		`MAIN_APP_MIGRATION_NOT_SUPPORTED`	Current M app version does not support migration. → 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 lockscreen activation page on M app.
		`UNKNOWN_ERROR`	Wrong integration or temporary error. In case of temporary error, lead to retry.
`encrypt` optional	-	An optional parameter to encrypt `UserProfile` when obtaining user info with M app. To encrypt `UserProfile` info, pass `true` for `encrypt`.

checkAvailability Error Flow

Advanced Usage

Communication Utils between M app and L app

Other than basic features provided by Migration SDK, you can also use additional commucation modules. Please refer to https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/403406895 doc.

Appendix

Creating market-ready L app using sample

sample_lock_light contains what this guide entails as well as other small features. Thus, by customizing the sample_lock_light a bit, you can get a simple market-ready version of a lockscreen app.

Configuration

Modify build.gradle : Replace my_app_key with the app key given for BuzzScreen integration process and applicationId to new lockscreen app package name.
Replace appKey used in BuzzScreen.init in the sample app code to the new value.
Modify AndroidManifest.xml : Replace <app_license> with the newly published value.
Setting M app lockscreen activation page deep link : Set DEEP_LINK_ONBOARDING in file App.java as M app lockscreen activation page deep link.

Design Change

Icon : change ic_launcher.png
Color : change the main color via modifying res/colors.xml
Logo : change the logo on tool bar at activity_main.xml

For more customization, please refer to https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/400949249 doc.

Buzzvil Developer Guides

BuzzScreen Migration SDK Usage

Introduction

Migration SDK Workflow

M App Migration Implementation

Basic Usage

1. Modify `build.gradle`

1) Add `manifestPlaceholders`

2) Add the followings to `dependencies`

BuzzScreen Integration as before

Migration library for M app

2. Add necessary codes to Application Class

3. Lockscreen Opt-in page modification

L app lockscreen activation process

4. Sign out process

+. Remove codes for BuzzScreen opt-in/out optional

Advanced Usage

Other useful methods

L App Migration Implementation

Basic Usage

1. Modify `build.gradle`

1) Add `manifestPlaceholders`

2) Add the followings to `dependencies`

BuzzScreen Integration

Migration library for L app

2. Modify `AndroidManifest.xml`

3. Add necessary codes to Application Class

4. Lockscreen Activation and Migration

checkAvailability Error Flow

Advanced Usage

Communication Utils between M app and L app

Appendix

Creating market-ready L app using sample

Configuration

Design Change

Introduction

Migration SDK Workflow

M App Migration Implementation

Basic Usage

1. Modify build.gradle

1) Add manifestPlaceholders

2) Add the followings to dependencies

BuzzScreen Integration as before

Migration library for M app

2. Add necessary codes to Application Class

3. Lockscreen Opt-in page modification

L app lockscreen activation process

4. Sign out process

+. Remove codes for BuzzScreen opt-in/out optional

Advanced Usage

Other useful methods

L App Migration Implementation

Basic Usage

1. Modify build.gradle

1) Add manifestPlaceholders

2) Add the followings to dependencies

BuzzScreen Integration

Migration library for L app

2. Modify AndroidManifest.xml

3. Add necessary codes to Application Class

4. Lockscreen Activation and Migration

checkAvailability Error Flow

Advanced Usage

Communication Utils between M app and L app

Appendix

Creating market-ready L app using sample

Configuration

Design Change

1. Modify `build.gradle`

1) Add `manifestPlaceholders`

2) Add the followings to `dependencies`

1. Modify `build.gradle`

1) Add `manifestPlaceholders`

2) Add the followings to `dependencies`

2. Modify `AndroidManifest.xml`