View Source

Please refer to the sample code before implementing into your application. - Github Link

BuzzScreen SDK Workflow

Index

Getting Started

1) Introduction

BuzzScreen SDK is Buzzvil's library for integrating BuzzScreen with Android lockscreen apps. Please check the notes below before proceeding integration.

Make sure to discuss with your account manager before start integrating.
It is required to submit the integrated APK file to your account manager for review before going live.

note

Following GDPR(General Data Protection Regulation), Buzzvil has implemented additional functions for user consent and updated privacy policy. For publishers who have EU users where GDPR applies, please refer to https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/409764056 for integration modification.

2) Requirements

Content

Details

Note

1

Android version

4.0.3 (API level 15) or newer
Officially supports Android 10

If minSdkVersion of your app is 14, refer to BuzzScreen SDK FAQ.

2

Meet Google Play's target API level requirement

In BuzzScreen SDK 2.0.2.0 or higher:

Use targetSdkVersion 28
Use compileSdkVersion 29 or higher

The policy goes into effect in

August 1st, 2019 for new apps and
November 1st, 2019 for app updates.

3

If Android Support Library version 26 or higher is used, the following is necessary:

Upgrade play service version to 12 or higher (recommend latest 15.0.1 version) due to the instability of GCM (Google Cloud Messaging).
com.android.support:appcompat-v7 version should be 26.0.2 or higher.

3) Prerequisites

	Content	Details	Note
1	Login API	Media API server for login to lockscreen app
2	Reward API	Media 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.
3	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. `app_license` : Please ask your account manager. (Required in the `AndroidManifest.xml` setting)	`app_key` : Required in the `BuzzScreen.init` method `app_license` : Required in the `AndroidManifest.xml` setting

1. `build.gradle` Setting

If buzzscreen-multiprocess SDK was previously implemented, switching the SDK to the regular version without any changes may cause some issues. Please refer to the related document(link) and remove android:process=":locker attribute in AndroidMafniest.xml.

Add the following codes to build.gradle in your app module.

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

dependencies {
    implementation 'com.buzzvil:buzzscreen:2.0.6.3'
}

dependencies {
    // For global publishers only
    implementation 'com.buzzvil.mediation:sdk-outbrain:2.5.3.1'
}

note

Guidelines

targetSdkVersion 28
compileSdkVersion 29 or higher
supportLibraryVersion = 26.1.0 or higher, recommends 28.0.0
Play Services libraries: refer to the sample code

Guidelines

targetSdkVersion 28
compileSdkVersion 29 or higher
supportLibraryVersion = 26.1.0 or higher, recommends 28.0.0
Play Services libraries: refer to the sample code

2. AdNetwork Integration

Technical account manager may provide information regarding additional adnetwork integration. If so, please add corresponding information to AndroidManifest.xml by referring to this document.

3. 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 Lock Screen

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

Content

Code

Place

Details

Initialize BuzzScreen

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 : app_key. Please find the app_key on your BuzzScreen dashboard.
- context : The application context (you can simply use this)
- lockerActivityClass : A Lock screen activity class.
  - You can simply use SimpleLockerActivity.class which is already provided in the SDK.
  - You can also implement your own lock screen 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.

Launch BuzzScreen

BuzzScreen.getInstance().launch()

Call this method in the very first activity of your app.

Sample Code

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        ...
        // app_key : `app_key` for SDK usage. Find it on your BuzzScreen dashboard.
        // SimpleLockerActivity.class : Lock screen activity class
        // R.drawable.image_on_fail : An image file to be displayed when either network error occurs or there is no campaign available temporarily
        BuzzScreen.init("app_key", this, SimpleLockerActivity.class, R.drawable.image_on_fail);
    }
}

2) Set User Profile

Note : If you do not set targeting information, ads with targeted will not be allocated to lockscreen, which will reduce the total number of ads users can see. If you do not have users' targeting information, please discuss with Buzzvil BD manager in advance.

Content

Code

Place

Details

Object for setting user profile information

BuzzScreen.getInstance().getUserProfile()

Keep in mind that you must set user information before calling BuzzScreen.getInstance().activate()

Returns UserProfile Class in which you can set user profile information

User ID

setUserId(String userId)

You must call setUserId(String userId) in order for the 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 a user’s userId can change by any means (e.g. re-installing or by a certain period of time), please discuss with Buzzvil BD manager in advance.

User age

setBirthYear(int birthYear)

Set age by Year of Birth of the user in 4 digits (e.g. 1988)
Ad campaigns will be targeted to specific demo by using this information

User gender

setGender(String gender)

Set gender by using predefined string constants below:
- UserProfile.USER_GENDER_MALE : For male
- UserProfile.USER_GENDER_FEMALE : For female
Ad campaigns will be targeted to specific demo by using this information

User region

setRegion(String region)

Set user’s region

Talk to your account manager for more information.

Else

Please refer to Custom Targeting doc.

You can target with specific user information you want.

3) Turn on/off the Lock Screen

Content

Code

Place

Details

BuzzScreen Activation

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 lock screen cycle will be managed automatically since then.

Activates BuzzScreen; BuzzScreen appears on the first screen after this method is called.

BuzzScreen Deactivation

BuzzScreen.getInstance().deactivate()

Turn off BuzzScreen.

BuzzScreen will no longer appear on the first screen after this method is called.

User logout

BuzzScreen.getInstance().logout()

Call this when the user has logged-out.

This method calls deactivate(), and removes all the UserProfile related info from the device.

Dismiss BuzzScreen activity when there’s no user activity
(Available in v. 1.9.2.3 or higher)

BuzzScreen.getInstance().setSettings(BuzzScreen.Settings.FINISH_IN_SEC, int set_seconds)

Call this method after BuzzScreen.init

Set time (in seconds) for which BuzzScreen disappears when there is no user activity.

Parameters
- set_seconds : When there’s no user interaction for this amount of time, BuzzScreen will disappear from the screen. (seconds)
Example
- Default: 60 seconds
- set_seconds = 30 : set time limit as 30 seconds
- set_seconds = 0 : Turns off this feature, i.e. BuzzScreen will not dissapear

Get callback when BuzzScreen is ready to be shown

BuzzScreen.getInstance().activate(ActivateListener listener)

You can get a callback when the lock screen is ready. Implement and provide the following interface and pass it as the parameter for the activate() method as BuzzScreen.getInstance().activate(ActivateListener listener)

public interface ActivateListener {
    void onReady();// This will be called when the first lockscreen is ready to be shown.
}

Customize Service Notification

Please refer to Lockscreen Service Notification doc.

If un-removable ongoing notification is created at Notification area after calling this method and you want to change it, please follow the guide. The guide shows you how to make use of the notification.

4. Security Lock UI Customization

This feature is available only for BuzzScreen SDK version 1.9.9.7 and above.

UI customization for ‘Security Lock’ is done after BuzzScreen.init() using the following methods:

backgroundResourceId(int resourceId): Sets background image for 'Swipe' mode
backgroundImageScaleType(enum ImageView.ScaleType): Sets alignment of background image for 'Swipe' mode (default: FIT_XY, Reference: link)
backgroundColor(int Color): Sets background color for 'Swipe' mode (default: Color.WHITE, Reference: link)
backgroundDimAlpha(float): Adjusts alpha value of black background for readability of clock and description (default: 0.7)
showClock(boolean): Determines whether to show clock feature or not (default: true)
showDescription(boolean): Determines whether to show description or not (default: true)

BuzzScreen.init("app_key", this, SimpleLockerActivity.class, R.drawable.image_on_fail, Constants.useGDPR ? BuzzScreen.PrivacyPolicy.GDPR : BuzzScreen.PrivacyPolicy.NONE);
                
BuzzScreen.getInstance().setSecurityConfiguration(
        new SecurityConfiguration.Builder().
                   backgroundResourceId(R.drawable.your_drawable).
                   backgroundImageScaleType(ImageView.ScaleType.FIT_CENTER).
                   backgroundColor(Color.WHITE).
                   backgroundDimAlpha(0.7f).                
                   showClock(true).
                   showDescription(true).
                   build());

5. Gaining “Draw Over Other Apps” permission

This feature is available only for BuzzScreen SDK version 2.0.5.4 and above.

Due to the restrictions in Android 10, enabling “Draw Over Other Apps” permission has become inevitable for using the lockscreen. Thus, we provide facile methods to gain the permission from users.

1) Lockscreen notification

Buzzvil Developer Guides > BuzzScreen SDK Basic Usage > image-20191125-122559.png

Automatically added feature
Not shown to users with Android 7 (Nougat) or below
Displayed every 6 hours until the permission has been enabled

2) In-App notification

Buzzvil Developer Guides > BuzzScreen SDK Basic Usage > image-20191125-122617.png

boolean BuzzScreen#showOverlayPermissionGuideDialogIfNeeded(Activity):
- Displays a popup dialog to gain the permission
- Recommended to be used when the app’s main UI is created (MainActivity#OnCreate()) or when the lockscreen has been enabled
- returns a boolean to show whether the popup dialog has been exposed or not

public class MainActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // (생략)
        BuzzScreen.getInstance().showOverlayPermissionGuideDialogIfNeeded(MainActivity.this);
    }

Clicking Yes leads the user to settings menu where the permission can be enabled. Once enabled, the user is redirected back to the previous UI.
Not shown to users with Android 7 (Nougat) or below and also if the permission has been already enabled.

6. Reward Accumulation (via Postback) - 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.

Procedure
1. Build a postback end-point server according to the Reward Accumulation Postback API guide.
2. Send the endpoint url to Buzzvil BD manager.

note

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.

Point accumulation request flow

If you need any of the following features, please refer to Advanced Usage doc.

Customized lock screen, slider UI, clock UI, or extra lock screen widgets.
Separating the lock screen process from main process for efficient memory usage.
and more!

Index

Getting Started

1) Introduction

2) Requirements

3) Prerequisites

1. build.gradle Setting

2. AdNetwork Integration

3. Call Methods

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

2) Set User Profile

3) Turn on/off the Lock Screen

4. Security Lock UI Customization

5. Gaining “Draw Over Other Apps” permission

1) Lockscreen notification

2) In-App notification

6. Reward Accumulation (via Postback) - Server to Server Integration

Point accumulation request flow

1. `build.gradle` Setting

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