Please refer to the sample included in the SDK before applying to your app. - M app / L app |
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.
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.
build.gradle
manifestPlaceholders
android { defaultConfig { // Please replace my_app_key with the app key provided for BuzzScreen integration process manifestPlaceholders = [buzzScreenAppKey:"my_app_key"] } } |
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 |
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' } |
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"); } }); } } |
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 | |
---|---|---|---|
1 | Set up a deeplink redirecting to lockscreen opt-in activity | - |
|
2 | Activate L app BuzzScreen |
|
|
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 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.
After integrating the migration SDK, BuzzScreen lifecycle of M app is automatically managed in the migration SDK and opt-out button may be provided only on the lockscreen for better user experience.
After integrating the migration SDK, BuzzScreen lifecycle of M app is automatically managed in the migration SDK and opt-out button may be provided only on the lockscreen for better user experience.
Content | Method | Detail | |
---|---|---|---|
Check if L app lockscreen is activated |
|
| |
Sync user info when it’s updated in M app |
|
| |
Customize market link for L app |
| When L app is installed through Parameters
| |
Activate L app lockscreen without running L app |
The method above differs from The method above differs from
| Activates lockscreen in L app. When activating lockscreen, user info set in the M app will be used. Parameters
|
Content | Detail | |
---|---|---|
1 | User Profile setting and Usage Agreement |
|
2 | Activation / Deactivation |
|
3 | Building L app |
|
build.gradle
manifestPlaceholders
android { defaultConfig { // Please replace my_app_key with the app key given for BuzzScreen integration process manifestPlaceholders = [buzzScreenAppKey:"my_app_key"] } } |
dependencies
Add the BuzzScreen library as well as the L app migration library. It requires BuzzScreen ver 1.6.3 or higher.
Existing BuzzScreen SDK is required to activate the lockscreen on L app. |
repositories { maven { url "https://dl.buzzvil.com/public/maven" } } ... dependencies { // The version MUST be same as migration-host's implementation 'com.buzzvil.buzzscreen.ext:migration-client: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' } |
AndroidManifest.xml
Renewed app_license
should be used and applied on L app in order to integrate BuzzScreen.
com.buzzvil.locker.mediation.baidu.plist
values are not necessary if you are using BuzzScreen SDK 1.9.0.7 or higher.
com.buzzvil.locker.mediation.baidu.plist
values are not necessary if you are using BuzzScreen SDK 1.9.0.7 or higher.
<manifest> <application> ... <!-- Configuration for BuzzScreen--> <!-- Replace <app_license> to new one that is different from existing one. --> <meta-data android:name="app_license" android:value="<app_license>" /> <!-- Not necessary with BuzzScreen SDK 1.9.0.7 or above --> <!-- Replace <plist> to new one that is different from existing one. --> <meta-data android:name="com.buzzvil.locker.mediation.baidu.plist" android:value="<plist>" /> </application> </manifest> |
Call Buzzscreen.init
for BuzzScreen integration and MigrationClient.init
for migration in that order.
Content | Method & Place | Detail | |
---|---|---|---|
Initialization code of L app for migration |
| Parameters
| |
Registering listener called when lockscreen of L app is deactivated |
| This method registers a listener that is called when lockscreen on L app is disabled either when
Parameters
|
public class App extends Application { @Override public void onCreate() { super.onCreate(); // The existing code to initialize Buzzscreen BuzzScreen.init("app_key", this, SimpleLockerActivity.class, R.drawable.image_on_fail); // Initialization for migration // The example code uses com.buzzvil.buzzscreen.sample_main_light for M app package name. MigrationClient.init(this, "com.buzzvil.buzzscreen.sample_main_light"); // An example of registering listener that is called when L app lockscreen is disabled by M app. MigrationClient.setOnDeactivatedByMainAppListener(new MigrationClient.OnDeactivatedByMainAppListener() { @Override public void onDeactivated() { Toast.makeText(App.this, "Disabling the lockscreen for Main App status change(Removed, Logout, etc.)", Toast.LENGTH_LONG).show(); } }); } } |
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.
During BuzzScreen activation process, BuzzScreen.getInstance().launch()
→ BuzzScreen.getInstance().activate()
is still used as in usual BuzzScreen activation process.
During BuzzScreen activation process, BuzzScreen.getInstance().launch()
→ BuzzScreen.getInstance().activate()
is still used as in usual BuzzScreen activation process.
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
Either M app lockscreen is being used
Or activating L app by calling MigrationHost.requestActivationWithLaunch()
Parameter | Response | Detail | ||
---|---|---|---|---|
|
|
|
| |
|
| M app is not installed. → In this case, redirect users to M app install process. | ||
| Current M app version does not support migration. → In this case, redirect users to update M app version. | |||
| This is returned when user information are not enough for BuzzScreen activation. → Users should be redirected to lockscreen activation page on M app. | |||
| Wrong integration or temporary error.
| |||
| - |
|
|
Other than basic features provided by Migration SDK, you can also use additional commucation modules. Please refer to Communication Utils doc.
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.
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.
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 Advanced Usage doc.
Please contact Buzzvil for any issues or questions regarding the sample app. |