Launcher Provider SDK

Launcher Provider SDK is a Launcher feature that enables native applications to get data about the current logged-in user status, store information, configuration, session data, etc.

Overview

Security management for workforce devices is a critical task for IT administrators. Having complete access and visibility to user information and device activity enables the organization to effectively implement security protocols and efficiently control who can view, share, or modify sensitive company data or resources. LauncherProvider is a Launcher feature that allows native applications to get data about the current logged-in user status, store information, configuration, session data, etc.

User Guide

1. If this feature is enabled in the configuration, the static class LauncherProviderHelper within the LauncherProvider’s AAR library will make provider data readily available and easily accessible.

2. Ideally, you should be able to retrieve information on specific users, stores, and sessions when the application resumes activity.

3. The Launcher has an authorizedClients section where customers and organizations can whitelist company-approved applications. The applications defined here are granted access to user information and device activity. Applications not defined here are automatically blacklisted from provider data access.

Feature Configuration

To set up LauncherProvider for a particular device profile or device group, please follow the steps below:

Enabling Provider on Gradle

In this example, the configuration declares the three external libraries that are needed to run the project: launcherProvider, Gson, and Timber.

// in your project's build.gradle file:
dependencies {
    ...
    implementation(​name​: ​'launcherProvider-x.x.x'​, ​ext​: ​'aar'​, ​version​: ​'x.x.x'​)
    implementation 'com.google.code.gson:gson:2.8.2'
    implementation 'com.jakewharton.timber:timber:4.7.1'
    ...
}

To access provider data on the AAR library, add launcherProvider-x.x.x.aar to the libs directory of the launcherProvider library.

implementation(​name​: ​'launcherProvider-x.x.x'​, ​ext​: ​'aar'​, ​version​: ​'x.x.x'​)

To access provider data on Gson and Timber libraries, add the following to the dependency list:

implementation 'com.google.code.gson:gson:2.8.2'
implementation 'com.jakewharton.timber:timber:4.7.1'

Add the Flat Directory to the repositories list in your Project build.gradle file to enable pulling from the libs directory. In this configuration, the online repositories mavenLocal, google, and jcenter host commonly used libraries. It also indicates how to access any additional external libraries that have been manually added to the libs directory.

allprojects {
    repositories {
        mavenLocal()
        google()
        jcenter()
        maven {
            ​// All of React Native (JS, Obj-C sources, Android binaries) is installed from npm
            u​rl​"​$rootDir​/../node_modules/react-native/android" ​
        }
        flatDir {
            dirs ​'libs' ​//this way we can find the .aar files in libs folder
        }
    ​}
}

Enabling Provider on Java

To retrieve information about the current user information, session, and site location, add the LauncherProviderHelper and Session classes in the configuration.

If getProviderInfo is marked as protected within SampleActivity, it indicates that current session information can only be retrieved or accessed from within this class.

Using LauncherProviderHelper and getCurrentSession, you can view the current user's user ID, username, groups, and access token.

If extendedAttributes is added to the configuration section, additional site information such as store number, store name, and device ID can also be retrieved or accessed.

import com.bluefletch.launcherprovider.LauncherProviderHelper;
import com.bluefletch.launcherprovider.Session;

...
public class SampleActivity extends Activity {

  // in this example, getProviderInfo is the local method used to retrieve the
  // current session information
  protected void getProviderInfo() {

    Session session = LauncherProviderHelper.getCurrentSession(this);

    // all fields should be present. If group is “*” then there is no
    // logged in session so the app should handle accordingly.
    //
    String userId = session.get(Session.USER_ID);
    String userName = session.get(Session.USER_NAME);
    String groups = session.get(Session.GROUPS);
    String accessToken = session.getExtendedAttribute("accessToken");

    // Get the site information from the config.  This information
    // is stored in the extendedAttributes.
    //
    Config config = LauncherProviderHelper.getCurrentConfig(this);
    String storeNumber = config.getExtAttr("siteId");
    String storeName = config.getExtAttr("siteName");
    String deviceId = config.getExtAttr("deviceId");

  }

Enabling Provider on Cordova

Install the Cordova plugin to access provider data:

//cordova plugin add com.phearme.cordovaplugin.contentproviderplugin

Add contentproviderplugin to the configuration. In this example, contentUri indicates where to locate the data; projection variable indicates which specific data will be retrieved; selection variable is used to filter the data; and, sortOrder indicates how retrieved data should be sorted.

if (window.plugins && window.plugins.contentproviderplugin) {
    window.plugins.contentproviderplugin.query({
        contentUri: "content://com.bluefletch.launcherprovider/session",
        projection: ["data"],
        selection: null,
        selectionArgs: null,
        sortOrder: null
    }, function (data) {
        console.log('session data is:', data);
        var sessionData = {};
        if (data.length > 0) {
            sessionData = JSON.parse(data[0]["DATA"]);
        }
        // get the user id
        var userid = sessionData.userId;
        var username = sessionData.userName;
        var groups = sessionData.groups;
        var extendedAttrs = JSON.parse(sessionData.extendedAttributes);
        var extAttrAccessToken = extendedAttrs.accessToken;

    }, function (err) {
        // use default
        console.log('session error:', err);
    });
}

Enabling Provider on React Native

On Android:

• Include the AAR for Launcher Provider

• Update the Gradle file to include Launcher Provider AAR

• Include React Bridge Code

• Update Main Application to include React Bridge Code

On React Code:

• Include the Launcher Exported Javascript

Enabling Provider on MAUI/C#

Installing the NuGet Package in Visual Studio

1. Download the NuGet Package onto your computer.

2. Create a folder on your computer to house the package and copy the package into that folder.

3. In your Visual Studio project go to Tools -> Nuget Package Manager -> Package Manager Settings -> Package Sources and click the + button in the top right.

4. Change the source to your created folder and click update, then OK.

5. Right-click your project file in the solution explorer and go to Manage NuGet Packages.

6. Click Browse and install the Launcher Provider Package.

Importing Launcher Provider into a file

Add the following lines to the top of your file:

using Com.Bluefletch.Launcherprovider;
using Com.Bluefletch.Launcherprovider.Models;

Note: These imports will only work for files targeting the Android platform.

Sample Code Block

using Android.App;
using Android.Content.PM;
using Android.OS;
using Com.Bluefletch.Launcherprovider;
using Com.Bluefletch.Launcherprovider.Models;

namespace SampleApp;

[Activity(Theme = "@style/Maui.SplashTheme", MainLauncher = true, LaunchMode = LaunchMode.SingleTop, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize | ConfigChanges.Density)]
public class MainActivity : MauiAppCompatActivity
{
    public static void Main()
    {
        CriteriaPattern criteriaPattern = new();

        var sessionJson = LauncherProviderHelper.GetCurrentSessionAsJson(Platform.AppContext);
        Console.WriteLine(sessionJson);

        var session = LauncherProviderHelper.GetCurrentSession(Platform.AppContext);
        var userId = session?.Get(Session.UserId);
        Console.WriteLine(userId);
        
    }
}

Whitelisting Applications

You can customize the applications that are permitted to access provider data. Add authorizedClients to the configuration.

{
    ...
    "authorizedClients" : [
       "com.mydomain.fulfillment",
       "com.mydomain.mobilepos"
    ],
}

Managing Storage and Retrieval of Provider Data

This configuration is responsible for managing provider data, such as storing and retrieving the user’s session data.

1. The instance LauncherSessionPackage overrides the getPackages method.

2. The method will get the list of packages that are already being used by the application.

3. The packages ModuleRegistryAdapter and LauncherSessionPackage will be added to the list.

4. Once added, the getPackages method will return the updated list to the application.

5. The application can use the updated list to manage the storage and retrieval of provider data.

public class LauncherSessionPackage implements ReactPackage {

    @Nonnull
    @Override
    public List<ViewManager> createViewManagers(@Nonnull ReactApplicationContext reactContext) {
        return Collections.emptyList();
    }

    @Override
    public List<NativeModule> createNativeModules( ReactApplicationContext reactContext ) {

        List<NativeModule> modules = new ArrayList<>();

        modules.add( new LauncherSessionProvider(reactContext) );

        return modules;
    }

}

Note for Android 11 and Above

For devices running Android 11 or above, add the following lines to the AndroidManifest.XML for any application that requires Launcher Provider access:

<queries>
    <provider
        android:authorities="com.bluefletch.launcherprovider"
        tools:replace="android:authorities" />
</queries>