BuzzScreen Extension SDK Usage
Introduction
"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:
Implement sign-in feature for lockscreen-exclusive applications - refer to https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/392462350 .
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 | |
---|---|---|
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 |
---|---|---|---|
Initialization code of M app for |
| Call in Application class. | Parameters
|
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 |
---|---|---|---|
Class for setting user profile |
| Should be set before activating L app lockscreen | You can get |
Set User Id required |
|
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 | |
User Age recommended |
| Set age by Year of Birth of the user in 4 digits (e.g, 1988) | |
User Gender recommended |
| Set gender by using predefined string constants below:
| |
User info Synchronizationrequired |
| Synchronize the user information with L app.
|
BuzzScreenHost.getUserProfile()
.setUserId(newUserId)
.setBirthYear(newBirthYear)
.setGender(newGender)
.sync(encrypt);
4. Controlling L app lockscreen
Content | Method | Detail |
---|---|---|
Sign out required |
| Call
|
Launch L app recommended |
| Launch the L app.
|
Check if L app lockscreen is activated optional |
| Returns |
Activate L app lockscreen optional |
| Activates lockscreen in L app. When activating lockscreen, user info set in the M app will be used. Parameters
|
Deactivate L app lockscreen optional |
| 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 thebuild.gradle
andBuzzScreen.init
method)app_license
: Please ask your account manager. (Required in theAndroidManifest.xml
setting)plist
: Please ask your account manager. (Required in theAndroidManifest.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 https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/396394955 doc.
Content | Detail | |
---|---|---|
1 | Setting User Profile | If you set up user targeting information such as gender and age in |
2 | Activation / Deactivation |
|
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.
|
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 |
---|---|---|
Initializing BuzzScreen required |
| Parameters
|
Initialization code of |
| Parameters
|
Listener for deactivation request from M app required |
| Parameters
|
Launch BuzzScreen required |
|
|
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 |
---|---|---|
Object for setting user profile information |
| You can set user profile information in this Class.
|
User Age recommended |
| Set age by Year of Birth of the user in 4 digits (e.g. 1988) |
User Gender recommended |
| Set gender by using predefined string constants below:
|
User Profile Synchronization optional |
| Use this method when you need to pass a changed
|
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 |
| This method is used to obtain data needed for BuzzScreen activation from M app asynchronously. Parameters
|
Activating BuzzScreen required |
| Turn on BuzzScreen.
|
Deactivating BuzzScreen required |
| 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.
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>"
inAndroidManifest.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.