BuzzScreen SDK Basic Usage

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

BuzzScreen SDK Workflow

Index

1 Getting Started
- 1.1 1) Introduction
- 1.2 2) Requirements
- 1.3 3) Prerequisites
2 1. build.gradle Setting
3 2. AdNetwork Integration
4 3. Call Methods
5 4. Security Lock UI Customization
6 5. Gaining “Draw Over Other Apps” permission
- 6.1 1) Lockscreen notification
- 6.2 2) In-App notification
7 6. Reward Accumulation (via Postback) - Server to Server Integration
- 7.1 Point accumulation request flow

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.

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

	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 https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/402653187.
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

	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 https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/396394955 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'
}

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

Content

Code

Place

Details

Initialize BuzzScreen
required

BuzzScreen.init(String appKey, Context context, Class lockerActivityClass, int imageResourceIdOnFail)

Place this code in the onCreate() in your application class.

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 https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/402391079.
- 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.

Launch BuzzScreen
required

BuzzScreen.getInstance().launch()

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

Sample Code

2) Set User Profile

Content	Code	Place	Details

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 Required	`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.
User age recommended	`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 genderrecommended	`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 optional	`setRegion(String region)`		Set user’s region
Else optional	Please refer to doc.		You can target with specific user information you want.

3) Turn on/off the Lock Screen

Content	Code	Place	Details

Content	Code	Place	Details
BuzzScreen Activation 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 lock screen cycle will be managed automatically since then.	Activates BuzzScreen; BuzzScreen appears on the first screen after this method is called.
BuzzScreen Deactivation required	`BuzzScreen.getInstance().deactivate()`	Turn off BuzzScreen.	BuzzScreen will no longer appear on the first screen after this method is called.
User logout required	`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 recommended (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 optional	`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)`
Customize Service Notification optional	Please refer to 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

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)

5. Gaining “Draw Over Other Apps” permission

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

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

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

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 guide.
2. Send the endpoint url to Buzzvil BD manager.