Bleesk Android SDK for Developers

Learn how to build context-aware app with Bleesk Android SDK.
Version 6.23

Add Bleesk SDK to your Android project

  1. Download Bleesk Android SDK (bleesksdk_6.23_android_all.zip)
    (NOTE: In the archive you will also find Android Studio project with sample BleeskSDK integration)
  2. Create new or open existing Android project.
  3. Extract zip archive and copy BleeskSDK-6.23.aar library file to your projects libs directory (create it if it isn’t there).
  4. Copy bleesk.gradle file to your projects app module directory
  5. Add to your app module build.gradle file

    apply from: 'bleesk.gradle'
    
    dependencies {
    
        implementation ( name:'BleeskSDK-6.23', ext:'aar')
        implementation bleesk_all
        
        ...
    }
    
    

    Note: remember to use flatDir in your grade configuration, like this:

    repositories {
        mavenCentral()
        flatDir {
            dirs 'libs'
        }
    }
  6. Add other required dependencies:

    implementation 'androidx.legacy:legacy-support-v4:1.0.0'
    implementation 'androidx.legacy:legacy-support-v13:1.0.0'
    implementation 'androidx.appcompat:appcompat:1.0.2'
    implementation 'androidx.multidex:multidex:2.0.1'

    Note: The minimum API level supported by this library is API 24 and the multidex should be set to true. Also, your app needs to be using the androidx libraries instead of the old support libraries (read about androidx migration here).

  7. Configure Google Play Services for your app:

    Add to the bottom of app->build.gradle file:

    apply plugin: 'com.google.gms.google-services'

    Create and add firebase config file - google-services.json (read how to do that here).

  8. If using Nearby Map feature add to your AndroidManifest in the application section:

    <meta-data android:name="com.google.android.geo.API_KEY" android:value="@string/google_maps_key" />

    Then in app->build.gradle->Default Config:

    resValue "string", "google_maps_key", (project.findProperty("GOOGLE_MAPS_API_KEY") ?: "")

    In gradle.properties file add:

    GOOGLE_MAPS_API_KEY=<YOUR_GOOGLE_MAPS_API_KEY>

    Note: change <YOUR_GOOGLE_MAPS_API_KEY> to GM API Key of yours (read more here).

  9. Remeber that your application should use Theme.AppCompat style or descendant.

  10. The easiest way is for your activities to extend BSKBaseActivity SDK class:

    public class MainActivity extends BSKBaseActivity {
        …
    }

    BSKBaseActivity is a simple wrapper on BSKDelegate interface, which handles all BleeskSDK callbacks and can be freely override for your apps needs.

    However, if you don't want to do that, just make the Activities implement BSKDelegate protocol and specify:

    BleeskSDK.delegate = this;

    to receive interface callbacks.

    In this case you should also manually pass the handler of requestPermissionResult to BleeskSDK, like this:

    @Override
    public void onRequestPermissionsResult( int requestCode, String permissions[], int[] grantResults)
    {
        super.onRequestPermissionsResult( requestCode, permissions, grantResults);
    
        BleeskSDK.onRequestPermissionsResult( requestCode, permissions, grantResults);
    }
  11. For proper handling of back button your activities should override the onBackPressed method:

    @Override
    public void onBackPressed() {
    
        if( BleeskSDK.shouldBreakOnBackPressed()) {
            return;
        }
        
        /* Add your code here */
    }

Initialize BleeskSDK and start detecting Bleesk spots

To start detecting beacon devices, geofences and WiFi spots and to be able to react on these, you need to initialise Bleesk SDK with your API Key

BleeskSDK.initWithAPIKey( Application app, Class mainActivityClass, String api_key);

You will find your API Key in Bleesk CMS in account settings.

Runtime Permissions v6.23

Handling of runtime permissions is done automatically by BleeskSDK. These include: read/write, location and camera (optionally) permissions.


I/O permissions are asked for just after the SDK is initialised, location permissions - before starting to detect Bleesk spots and camera when the barcode scanner is to be opened.

You can override the automation process, by returning true from one of below:

public Boolean BSK_ShouldBreakIOPermissionsRequest();
public Boolean BSK_ShouldBreakLocationPermissionsRequest();
public Boolean BSK_ShouldBreakCameraPermissionsRequest();

After you you have collected proper permissions customly, you need to call:

BleeskSDK.IOPermissionsGranted();
BleeskSDK.locationPermissionsGranted();


When user declines any permissions prompted for by BleeskSDK, the rationale prompt can be provided:

public void BSK_ShouldPromptForCameraPermissionRationale();
public void BSK_ShouldPromptForIOPermissionsRationale();
public void BSK_ShouldPromptForLocationPermissionsRationale();

Just put a custom, rationale prompt logic in the methods above.



When app user accepts permissions prompted by BleeskSDK, interface methods are triggered:

public void BSK_LocationPermissionsGranted();
public void BSK_IOPermissionsGranted();

You can force BleeskSDK to prompt for permissions at any time that suits your needs, by:

BleeskSDK.requestIOPermissions();
BleeskSDK.requestLocationPermissions();

Displaying detected campaigns

Turn on nearby mode with:

static public void setNearbyMode( Boolean t);

When a campaign is ready to be displayed to the user, a BSK_ShouldDisplayContent interface method is being called.

In order to view the content template automatically, get current content theme fragment with

static public Fragment getCurrentContentFragment();
then switch current activity fragment with the proper fragment manager.

Sometimes, especially with Loyalty campaigns, you will get BSK_ShouldRefreshContent interface method calls. This means that the view should be refreshed because the content might have changed - f.e. the points status of loyalty campaign has changed.

Displaying detected Physical Web URLs

When a Physical Web URL is found nearby, the BSK_ShouldDisplayURL interface method is called. You can respond to that method by getting current URL content view fragment:

static public Fragment getCurrentURLContentFragment();

and switch it with proper fragment manager.

Handling listing of Bleesk Contents (Offers)

In BleeskSDK there are 4 lists of campaigns:

  • All contents list: contains all not loyalty, not URL contents
  • Pinned contents list: contains pinned (saved) contents (URLs and standard contents)
  • Loyalty contents list: contains loyalty contents
  • URL contents list: contains Physical Web URL contents
All above are stored as BSKContentsListItem objects, and can be “retrieved” at any time with certain methods:

static public ArrayList<BSKContentsListItem> getPinnedContentsListItems();
static public ArrayList<BSKContentsListItem> getAllContentsListItems();
static public ArrayList<BSKContentsListItem> getURLContentsListItems();
static public ArrayList<BSKContentsListItem> getLoyaltyContentsListItems();

In order to display listed contents item, you should:

static public void contentListItem_prepareView( BSKContentsListItem item)

This method will trigger proper interface methods depending on the type of ContentsListItem:

public void BSK_ShouldDisplayContent();

or

public void BSK_ShouldDisplayURL();

Handle those callbacks same as described in “Displaying detected campaigns” and “Displaying detected Physical Web URL’s” section above.

When the status of lists changes, proper delegate methods are triggered:

public void BSK_PinnedContentsListItem_Added(BSKContentsListItem item)
public void BSK_PinnedContentsListItem_Removed(BSKContentsListItem item)

public void BSK_AllContentsListItem_Added(BSKContentsListItem item)
public void BSK_LoyaltyContentsListItem_Added(BSKContentsListItem item)
public void BSK_URLContentsListItem_Added(BSKContentsListItem item)

Whenever BSKContentsListItem is in use, you should determine if it’s a BSKURLContent or BSKContent by using isURLContent method of BSKContentsListItem object .

Other BleeskSDK lists methods:

static public Boolean contentsListItem_togglePinned( BSKContentsListItem item);

Toggles pinned option of list item

static public void contentsListItem_remove( BSKContentsListItem item)

Removes list item

static public BSKVenue contentsListItem_getVenue( BSKContent content)

Retrieve information about item's venue

static public BSKContentsListItem contentsListItem_findForContent( BSKContent content)

Get BSKContentsListItem object for certain BSKContent

static public BSKContentsListItem contentsListItem_findForURL( String url)

Get BSKContentsListItem object for certain Physical Web URL

Scanning Bleesk barcodes

The easiest way to scan barcodes is to display embedded Barcode Scanner View.

In order to view the Barcode Scanner automatically, get the fragment with:

static public Fragment getBarcodeScannerFragment();

then switch current activity fragment with the proper fragment manager.

When a proper barcode is scanned, the:

BSK_RangedBarcodeWithContent( BSKBarcode, BSKContent)

delegate method is called, and further

BSK_ShouldDisplayContent()

If you’d like to use a custom barcode scanner, use:

static public Boolean handleScannedBarcodeWithCode( String code)

If the code is not recognised the result is false, otherwise the result is true and delegate methods as above are called.

Displaying Nearby Map v6.23

In order to show the Nearby Map View, get it's Fragment with:

static public Fragment getNearbyMapFragment();

then switch current activity fragment with the proper fragment manager.

When user taps on view's close button, a interface method is called:

public void BSK_ShouldCloseNearbyMapView()

You should remove it's Fragment from the view stack.

Handling InApp URL actions

When user triggers inApp URL action the:

public void BSK_ShouldDisplayInAppURLView( String url, Fragment urlDisplayFragment);

interface method is called. You can handle this in two ways, by displaying the embedded InApp URL browser view fragment (urlDisplayFragment) or by handling the URL otherwise.

Using Loyalties

When a detected campaign is assigned to a Loyalty Campaign with Loyalty Content Template, it is added to the LoyaltyContentsList (see “Handling listing of Bleesk Contents (Offers)” above).

Retrieve the information about Loyalty program with:

static public BSKLoyalty getLoyaltyForContent( BSKContent content)

(NOTE: BSKContent object is accessible from BSKContentsListItem object)

BSKLoyalty object contains information about:

  • type: loyalty type (BSKLOYALTY_TYPE_POINTS, BSKLOYALTY_TYPE_STAMPS or BSKLOYALTY_TYPE_COUPON)
  • maxPoints: maximum number of points in this Loyalty program
  • points: current points status
  • auto_points: should points be granted automatically or need button confirmation
  • pinConfirm: if auto_points == false , pinConfirm determines if user should enter Venue Pin Code before points should be granted

Handling information about Venues

In order to access information about Venue under which specific campaign is set active, get BSKVenue object from the list view item:

static public BSKVenue contentsListItem_getVenue( BSKContent content)

BSKVenue object contains information about:

  • name: Venue name
  • is_prime_venue: whether this Venue is a Prime
  • pinCode: Pin Code used for loyalties verification
  • location: raw Venue location as “latitude;longitude” coordinates string
  • locality: determined from location and saved Venue locality (in most cases - City name)
  • splashImgFile: downloaded image File

Do Not Disturb Mode & Contents categories

Do Not Disturb Mode when it is set to true, disables all ranging activities, concerning beacons, wifis and geofences.

Use below methods to control it:

static public void setDoNotDisturbMode(Boolean t);
static public Boolean isDoNotDisturbMode();


In BleeskSDK Contents categories are specified as numbers = 1-based indexes, by default 1 - 6 (category names might change depending on custom CMS settings or translations).

You can adjust current category settings by:

static public ArrayList<Integer> getSelectedCategories();
static public Boolean isSelectedCategory( Integer idx);
static public void setSelectedCategories( ArrayList<Integer> selCats);

Setting user profile

For users registration use:

static public void registerUser( String firstName, String lastName, String email)

In order to specify users profile, call this method

static public void setUserProfile( int gender, int year, ArrayList<Integer> selectedCategories);

Gender should be specified as one from below:

BleeskSDK.BSKPROFILE_GENDER_MALE
BleeskSDK.BSKPROFILE_GENDER_FEMALE

selectedCategories should be an array list of Integers from available categories range.

For logging out user:

static public void signOutUser()

Extended user profile v6.23

Since version 6.20 of BleeskSDK a new extended user profile is available. It contains additional data fields among with user's photo image.


BSKProfile object contains:

  • name
  • surname
  • email
  • phone
  • company
  • www
  • gender: BleeskSDK.BSKPROFILE_GENDER_MALE or BleeskSDK.BSKPROFILE_GENDER_FEMALE
  • birthDate
  • imgFile: profile image File
  • imgPath: profile image URL

For setting up extended profile use:

static public void setUserProfile( BSKProfile profile, ArrayList<Integer> selectedCategories);

BleeskSDK contains a profile preview feature, which allows to preview user profile, whether it is a registered user profile or a profile collected via Contact Exchange feature.

Before a profile preview can be displayed, it need's to be prepared using:

BleeskSDK.profile_prepareForPreview()
or
BleeskSDK.profile_prepareForPreview( BSKProfile profile)

On success, an interface method is called:

public void BSK_ShouldDisplayProfilePreviewView()

Act on it, by getting Profile Preview Fragment, and displaying it in your activity:

BleeskSDK.getProfilePreviewFragment()

Using Contact Exchange feature v6.23

Contact Exchange feature enables user to seamlessly exchange profile data between app users. You can read more about this and other Bleesk's app-for-events features on our webpage (http://beaconeventapp.com/).


All Profiles (Contacts) collected by Contact Exchange feature are stored in Profiles lists, which are devided into: Pending Profiles and Added Profiles. First ones are those collected by the contact exchange feature but not added yet.


To get list of profiles use:

BleeskSDK.getAddedProfilesListItems()
and
BleeskSDK.getPendingProfilesListItems()

In order to add Pending Profile to Added Profile list call:

BleeskSDK.addPendingProfileToAddedProfilesList( long profile_deviceID)

with Pending Profile deviceID.


You can remove profile lists items with:

BleeskSDK.removeAddedProfileListItemWithDeviceID( long deviceID)
and
BleeskSDK.removePendingProfileListItemWithDeviceID( long deviceID)

You can also:

BleeskSDK.getAddedProfileListItemWithDeviceID( long deviceID)
and
BleeskSDK.getPendingProfileListItemWithDeviceID( long deviceID)


In order to detect Profiles that are being broadcasted by others, you need to enable it

BleeskSDK.setScanForProfilesMode( true)

Remember to disable it when appropriate.


If user wants to share his profile with others, he needs to broadcast it.
BleeskSDK provides ready-to-use "Broadcast Profile" view, which can be displayed, by acquiring its Fragment with:

BleeskSDK.getBroadcastingProfileFragment()

and switching your activity's current fragment.


Alternatively, you can start broadcasting ad hoc:

BleeskSDK.profile_startBroadcasting()

and stop:

BleeskSDK.profile_stopBroadcasting()

Note: Contact Exchange feature is done thanks to the BLE connectivity, therefore bluetooth must be ON in both - broadcasting and receiving devices. Exchange distance is up to 15 m - depending on surrounding environment.


Other BSKDelegate interface methods:

public void BSK_ProfileListItem_Added( BSKProfile item)
public void BSK_ProfileListItem_Removed( BSKProfile item)

public void BSK_PendingProfileListItem_Added( BSKProfile item)
public void BSK_PendingProfileListItem_Removed( BSKProfile item)

Handling Remote (Push Notifications) and Local Notifications

BleeskSDK allows handling of Bleesk related push notifications, which means that push message sent from Bleesk CMS will be delivered and properly handled by your custom Android app.

First you need to order Push Notifications Module for Bleesk (contact billing@bleesk.com for details).

And that’s it - now your app will receive push notifications sent by Bleesk CMS - it is all handled automatically by BleeskSDK.

After the remote notification is delivered to the application, it is being added to the proper ContentsList (more about lists in BleeskSDK - “Handling listing of Bleesk Contents (Offers)” section above) and if the app is not active (background mode), a notification is displayed to the user .

By default remote notifications are turned on, you can disable that feature by setting false to:

BleeskSDK.setAllowRemoteNotifications( false)

When user taps on the notification, whether it was a local or remote notification, the app is being opened and interface method is called:

public void BSK_ShouldDisplayContentFromNotification( BSKContent content);

or

public void BSK_ShouldDisplayURLFromNotification( BSKURLContent urlContent);

You might react on these by showing custom contents list view of your application or displaying the proper content view as described in “Handling listing of Bleesk Contents (Offers) - displaying listed offers” section above.


Before a notification is displayed to the user, you can customise it by returning updated Notification.Builder from below interface method:

public Notification.Builder BSK_WillPostNotificationWithBuilder( Notification.Builder builder)

You might want to customise the Notification Channel as well, then use this and return updated NotificationChannel

public NotificationChannel BSK_WillCreateNotificationChannel( NotificationChannel channel)

Application background mode v6.23

BleeskSDK allows detecting beacons and other spots in background mode. This is a default behaviour, but it can be disabled by:

BleeskSDK.setAllowBackgroundMode( false)

When app is in background mode, a foreground service notification is displayed as a requirement since Android 8. You can customise this notification by returning updated Notification.Builder from below interface method:

public Notification.Builder BSK_WillCreateBackgroundNotificationWithBuilder( Notification.Builder builder)

You might want to customise the Notification Channel used for foreground service notification, then use this and return updated NotificationChannel

public NotificationChannel BSK_WillCreateBackgroundNotificationChannel( NotificationChannel channel)

Additional possibilities for triggering campaigns and adding loyalty points

BleeskSDK allows to customary trigger Bleesk Campaigns, which also provides way to add loyalty points for custom actions.

To trigger Bleesk Campaign (and add loyalty points for campaigns with assigned loyalty program) use:

static public void triggerCampaignWithID( long campaign_id)

You can also trigger Bleesk Content directly:

static public void triggerContentWithID( long content_id)

This might be helpful as well for custom universal links handling in you app.

Controlling BleeskSDK options

Menu icon

When user taps on “menu” icon in the content templates view header, a BSK_ShouldDisplayMenu interface method is called.
In order to give full experience to the customer you should implement this method to show proper menu view of your application (f.e. a sidebar view).

Social Share

Social Share for offers is available in BleeskSDK by default. You can control if certain content should be shared after user tapped the “share” icon in the content templates view header, by returning false from:

public Boolean BSK_ShouldSocialShareContent(BSKContent content, String image_path, String share_text);


Header icons

If you wish to disable menu icon, pin icon or share icon in contents headers use:

static public void setShowHeaderPinBtn( Boolean t);
static public void setShowHeaderMenuBtn( Boolean t);
static public void setShowHeaderShareBtn( Boolean t);


Other BleeskSDK options

static public void setShowNotifications(Boolean t)

Determines if local notifications should be displayed to the user when a new campaign is detected. Default is true.

static public void setCollectAnalytics(Boolean t)

Set to false, if you don’t need to collect analytics data. Default is true.

static public void setRangePhysicalWebURLs(Boolean t)

Set to false, if you don’t want to range Physical Web URL’s. Default is true.

static public void setAllowBackgroundMode( Boolean t)

Set to false, if you don't want the app to detect bleesk spots in background mode. Default is true.

static public void setAllowRemoteNotifications( Boolean t)

Set to false if you don't want to receive remote (push) notifications. Default is true.

BSKDelegate methods

Beacons

public void BSK_WillEnterBeaconZone();

User will enter the beacons zone


public void BSK_WillLeaveBeaconsZone();

User will leave the beacons zone


public void BSK_NewBeaconRanged( BSKBeacon beacon);

A new beacon was ranged in current beacons path


public void BSK_RangedBeacon( BSKBeacon beacon);

A beacon was ranged, not yet determined proximity, nor campaign settings


public void BSK_RangedBeaconWithContent( BSKBeacon beacon, BSKContent content);

A beacon was ranged, campaign settings and proximity testing passed


Geofences

public void BSK_WillEnterGeofencesZone();

User will enter Geofences zone


public void BSK_WillLeaveGeofencesZone();

User will leave Geofences zone


public void BSK_NewGeofenceRanged( BSKGeofence geofence);

A new geofence was ranged in current geofence path


public void BSK_RangedGeofence( BSKGeofence geofence);

A geofence was ranged, not yet determined proximity, nor campaign settings


public void BSK_RangedGeofenceWithContent( BSKGeofence geofence, BSKContent content);

A geofence ranged with campaign settings and proximity passed


Wifis

public void BSK_WillEnterWifiZone();

User will enter Wifis zone


public void BSK_WillLeaveWifiZone();

User will leave Wifis zone


public void BSK_NewWifiRanged( BSKWifi wifi);

A new wifi was ranged in current wifi path


public void BSK_RangedWifi( BSKWifi wifi);

A wifi was ranged, not yet determined proximity, nor campaign settings


public void BSK_RangedWifiWithContent( BSKWifi wifi, BSKContent content);

A wifi ranged with campaign settings and proximity passed


Barcodes

public void BSK_RangedBarcodeWithContent( BSKBarcode barcode, BSKContent content);

A barcode was scanned, campaign settings passed


Physical Web URL's

public void BSK_NewPhWURLRanged( String url);

A new Physical Web URL ranged


public void BSK_RangedPhWURL( BSKURLContent urlContent);

A Physical Web URL ranged, head data downloaded


Other

public void BSK_WillDownloadContentAssets();

Assets for detected campaign will be downloaded


public void BSK_DidDownloadContentAssets();

Finished downloading detected campaign assets


public void BSK_ShouldDisplayContent();

Current content should be displayed


public void BSK_ShouldDisplayContentFromNotification( BSKContent content);

Application was opened by notification - the content should be displayed


public void BSK_ShouldDisplayURLFromNotification(BSKURLContent urlContent);

Application was opened by notification - the URL content should be displayed


public void BSK_ShouldRefreshContent();

The content view should be refreshed - used with loyalty contents - refreshing current points status


public void BSK_ShouldCloseContentPreview();

The content theme fragment should be closed - user tapped the preview close header button


public Boolean BSK_ShouldSocialShareContent(BSKContent content, String image_path, String share_text);

User tapped on offer share button;
Return true if the social share menu should be displayed;
image_path contains a path to the share image file;


public void BSK_ShouldDisplayMenu();

User taped on “menu” icon on left side of the contents header


public void BSK_ShouldDisplayProfileSettings();

User has not filled profile data yet - you should navigate to settings view


public void BSK_ShouldDisplayProfileRegister();

User haven't registered yet or has signed out - you should navigate to register view of your application


public void BSK_PinnedContentsListItem_Added( BSKContentsListItem item);

New content was added to “pinned” contents list


public void BSK_PinnedContentsListItem_Removed( BSKContentsListItem item);

A content was removed from “pinned” contents list


public void BSK_AllContentsListItem_Added( BSKContentsListItem item);

New content was added to all contents list


public void BSK_LoyaltyContentsListItem_Added( BSKContentsListItem item);

New content was added to loyalty contents list


public void BSK_URLContentsListItem_Added( BSKContentsListItem item);

New content was added to URL contents list


public void BSK_ShouldDisplayInAppURLView(String url, Fragment urlDisplayFragment);

User tapped on close arrow of the InApp URL browser view, the fragment should be closed properly


public void BSK_ShouldCloseInAppURLView();

The inApp URL fragment should be closed - user tapped the close header button


public void BSK_ShouldCloseBarcodeScannerView();

The barcode scanner fragment should be closed - user tapped the close header button


public void BSK_OfflineStatusChanged( Boolean isOnline);

The offline/online status has been changed


public Boolean BSK_ShouldActivateBT();

Return true if bluetooth should be auto activated


public Boolean BSK_ShouldActivateMobileData();

Return true if mobile data should be auto activated


static public void setRangeWifis( Boolean t)

Turn on / off wifi ranging


static public void setAppName( String app_name)

Set Application name for alerts and communication