This guide documents the legacy process for including the nudge® mobile library in an Android application for an implementation that includes the optional location-based messaging functionality add-on. The current premium guide for integration with location-based messaging can be found here.

Not sure if the integration you are building includes location-based messaging? Click Submit a request above, or contact us at support@larky.com! 

Library version

As of this writing the latest library is releases.com.larky:nudge:3.6.0

Requirements:

This guide assumes you're targeting Android SDK 21 or above and that you have a valid nudge API key. 

If you do not yet have a nudge API key, please contact support@larky.com with the following information:

• Your organization name
• To create an initial portal user we also need the following
  • User first name
  • User last name
  • User email

Before getting started, please make sure you are following those minimum requirements:

• Gradle: version 8.7
• Android plugin for Gradle: version 8.6.0
• Android Studio: version 2022.2.1 Patch2
• Android compileSdkVersion: 35
• Android minSdkVersion: 21+
• Google services: 4.3.15
• In gradle.properties:
  • android.useAndroidX=true
  • android.enableJetifier=true

Note on location permissions

Requesting background location access permission, which is required for full functionality, is a two-step process starting with Android 11 (SDK 30). The end-user will initially be prompted to grant access "while using the app" and then they will be prompted for permission to access location in the background.

Importing the library

nudge is distributed through maven.

Adding maven to your project-wide build.gradle file

This should be near imports like jcenter and google. It is recommended to re-sync your project after making build.gradle changes to ensure dependencies are working and up to date

allprojects {
    repositories {
        google()
        jcenter()

        // Add the code starting here
        maven {
            url 'https://maven.nudge.larky.cloud' 
        }
        // And ending here!
    }
}

Adding the nudge library as a dependency to your app-specific build.gradle file

Replace <LIB_VERSION_NUMBER> with the appropriate library version (listed above).

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'com.android.support:appcompat-v7:26.1.0'
    testImplementation 'junit:junit:4.12'

     // Add this line
    implementation 'releases.com.larky:nudge:<LIB_VERSION_NUMBER>' }

Adding the library to your project

Now that you've got the nudge library imported, we just need to add it into your app's functionality!

Find the file you want to add nudge to

We recommend doing this wherever you authenticate your users. This is often your MainActivity.java page.

Import the package alongside your other imports

import com.larky.nudge.Nudge;

Declare the nudge object

This is usually done at the activity level scope

private Nudge MyNudge;

private var myNudge: Nudge? = null

You can initialize nudge by using NudgeBuilder

In the OnCreate method of your activity, initialize the nudge library as follows

this.myNudge = new Nudge.NudgeBuilder()
                     .setActivity(this)
                     .setApplicationContext(getApplicationContext())
                     .setApiKey("<YOUR_API_KEY_HERE>")
                     .setResourceId(<RESOURCE_ID>)
                     .setPersistentNotificationTitle("<TITLE>")
                     .setPersistentNotificationText("<TEXT>")
                     .setStatusUpdateCallback(new MyNudgeStatusNotifier())
                     .setUserFederationId(<USERID_ID>)
                     .setEnabled(true)
                     .setDisclosureDialogEnabled(true)
                     .setPromptPushNotifications(true)
                     .setBackgroundDisclosureDialogEnabled(true)
                     .setLarkyNudgePermissionListener(result -> { 
                       switch(result) { 
                           
                         // The library prompted the user for foreground permissions and the user accepted. 
                         // The library did not prompt for background permissions 
                         case Nudge.LarkyNudgePermissionListener.FOREGROUND_GRANTED: 
                           break;
                                  
                         // The library prompted the user for foreground permissions and the user denied 
                         // The library did not prompt for background permissions 
                         case Nudge.LarkyNudgePermissionListener.FOREGROUND_DENIED:
                           break;
                                  
                         // The library did not prompt for foreground permissions
                         // The library did not prompt for background permissions 
                         case Nudge.LarkyNudgePermissionListener.FOREGROUND_BYPASS: 
                           break;
                                  
                         // The library prompted the user for background permissions and the user accepted
                         // Foreground permissions were either prompted for and accepted or were previously 
                         // accepted and no prompting occurred 
                         case Nudge.LarkyNudgePermissionListener.BACKGROUND_GRANTED: 
                           break;
                                  
                         // The library prompted the user for background permissions and the user denied 
                         // Foreground permissions were either prompted for and accepted or were previously 
                         // accepted and no prompting occurred 
                         case Nudge.LarkyNudgePermissionListener.BACKGROUND_DENIED: 
                           break;
                              
                         // The library did not prompt for background permissions 
                         // Foreground permissions were either prompted for and accepted or were previously 
                         // accepted and no prompting occurred 
                         case Nudge.LarkyNudgePermissionListener.BACKGROUND_BYPASS: 
                           break;
                              
                         // Catch all for unsupported or unexpected cases 
                         case Nudge.LarkyNudgePermissionListener.DEFAULT: 
                           break;
                         }
                     }).build();

myNudge = Nudge.NudgeBuilder()
                     .setActivity(this)
                     .setApplicationContext(getApplicationContext)
                     .setApiKey("<YOUR_API_KEY_HERE>")
                     .setResourceId(<RESOURCE_ID>)
                     .setPersistentNotificationTitle("<TITLE>")
                     .setPersistentNotificationText("<TEXT>")
                     .setStatusUpdateCallback(MyNudgeStatusNotifier())
                     .setUserFederationId(<USERID_ID>)
                     .setEnabled(true)
                     .setDisclosureDialogEnabled(true)
                     .setBackgroundDisclosureDialogEnabled(true)
                     .setPromptPushNotifications(true) 
                     .setLarkyNudgePermissionListener(result Int -> { 
                       when(result) { 
                           
                         // The library prompted the user for foreground permissions and the user accepted. 
                         // The library did not prompt for background permissions 
                         Nudge.LarkyNudgePermissionListener.FOREGROUND_GRANTED -> {
                         }
                                  
                         // The library prompted the user for foreground permissions and the user denied 
                         // The library did not prompt for background permissions 
                         Nudge.LarkyNudgePermissionListener.FOREGROUND_DENIED -> {
                         }
                                  
                         // The library did not prompt for foreground permissions
                         // The library did not prompt for background permissions 
                         Nudge.LarkyNudgePermissionListener.FOREGROUND_BYPASS -> { 
                         }
                                  
                         // The library prompted the user for background permissions and the user accepted
                         // Foreground permissions were either prompted for and accepted or were previously 
                         // accepted and no prompting occurred 
                         Nudge.LarkyNudgePermissionListener.BACKGROUND_GRANTED -> { 
                         }
                                  
                         // The library prompted the user for background permissions and the user denied 
                         // Foreground permissions were either prompted for and accepted or were previously 
                         // accepted and no prompting occurred 
                         Nudge.LarkyNudgePermissionListener.BACKGROUND_DENIED -> { 
                         }
                              
                         // The library did not prompt for background permissions 
                         // Foreground permissions were either prompted for and accepted or were previously 
                         // accepted and no prompting occurred 
                         Nudge.LarkyNudgePermissionListener.BACKGROUND_BYPASS -> { 
                         }
                              
                         // Catch all for unsupported or unexpected cases 
                         Nudge.LarkyNudgePermissionListener.DEFAULT -> { 
                         }
                      }
                     }).build()

Parameters:

• setActivity(Activity): Required - The current Android activity is needed by the library to display location permissions dialogs
• setApplicationContext(Context): Required - The application context is needed to display OS location permission dialogs
• setApiKey(String): Required - This is your Larky provided nudge API key
• setResourceId(int): Optional - ID of icon to be displayed in nudge notifications. 
  NOTE: The icon must be white and have a transparent background (.png)
• setPersistentNotificationTitle(String): Optional - Override default persistent notification title for background location usage. Example: "Monitoring for activity"
• setPersistentNotificationText(String): Optional - Override default persistent notification text for background location usage. Example: "Keeping you informed of important notices"
• setStatusUpdateCallback(MyNudgeStatusNotifier): Optional - Provide the listener to the client when the Active status of the library changes.
• setUserFederationId(String): ID value identifying the logged-in app user, enabling targeted messaging to account holders. See this article for more details, including suggested values to use for this parameter.
• setEnabled(Boolean - default = true): Optional - Programmatic way to enable or disable Nudge library
• setDisclosureDialogEnabled(Boolean - default = true): Optional -

  • If set = True, the library will show a prominent disclosure text and prompt the user for foreground location permissions when applicable

  • If set = False, the library will not display a disclosure nor prompt for foreground permissions. In that case it is assumed that the integrator app is handling prompting for foreground location permissions

  • Version specifics:

    • For Android 10 this parameter is used to request both foreground and background location permissions

    • For Android 9 and below this parameter is used to request location permissions (there is no foreground/background distinctions)

• setBackgroundDisclosureDialogEnabled(Boolean - default = true): Optional -

  • If set = True, the library will show a prominent disclosure text and prompt the user for background location permissions when applicable

  • If set = False, the library will not display a disclosure nor prompt for background permissions. In that case it is assumed that the integrator app is handling prompting for background location permissions

  • Version specifics:

    • For Android 10 and below this parameter is not used and has no effect

• setPromptPushNotifications(Boolean - default=true) Optional -
  • If set = True, if the device is using Android 13 or higher, the library will prompt the user for push notification permissions on initialization
  • If set = False, if the device is using Android 13 or higher, the library will not prompt the user for push notification permissions on initialization. This is useful if you already have code in your library that would handle this permission.
    
• setLarkyNudgePermissionListener(): Required - Provides information on notifications and location permission user responses. See below for further details

Notification and Location Permission Listener:

A listener is provided to inform you of the user response to notifications and foreground/background location permission requests, which are presented via alert dialogs upon the initial instantiation of the nudge library.  The results codes are:

• NOTIFICATIONS_GRANTED
  •  
• NOTIFICATIONS_DENIED
  •  
• FOREGROUND_GRANTED
  • The library prompted the user for foreground permissions and the user accepted.
  • The library did not prompt for background permissions
  • Event triggered by: SDK 30-v11, SDK 30-v10, SDK 29-v11, SDK 29-v10
  • Not triggered by: SDK 30-v9
• FOREGROUND_BYPASS
  • The library did not prompt for foreground permissions
  • The library did not prompt for background permissions
  • Event triggered by: SDK 30-v11, SDK 30-v10, SDK 29-v11, SDK 29-v10
  • Not triggered by: SDK 30-v9
• FOREGROUND_DENIED
  • The library prompted the user for foreground permissions and the user denied
  • The library did not prompt for background permissions
  • Event triggered by: SDK 30-v11
  • Not triggered by: SDK 30-v10, SDK 30-v9, SDK 29-v11, SDK 29-v10
• BACKGROUND_GRANTED
  • The library prompted the user for background permissions and the user accepted
  • Foreground permissions were either prompted for and accepted or were previously accepted and no prompting occurred
  • Event triggered by: SDK 30-v11, SDK 30-v10, SDK 30-v9, SDK 29-v11, SDK 29-v10, SDK 29-v9
  • Not triggered by: none
• BACKGROUND_BYPASS
  • The library did not prompt for background permissions
  • Foreground permissions were either prompted for and accepted or were previously accepted and no prompting occurred
  • Event triggered by: SDK 30-v11, SDK 30-v10, SDK 30-v9, SDK 29-v11, SDK 29-v10, SDK 29-v9
  • Not triggered by: none
• BACKGROUND_DENIED
  • The library prompted the user for background permissions and the user denied
  • Foreground permissions were either prompted for and accepted or were previously accepted and no prompting occurred
  • Event triggered by: SDK 30-v11, SDK 30-v10, SDK 30-v9, SDK 29-v11, SDK 29-v10, SDK 29-v9
  • Not triggered by: none
• DEFAULT
  • Catch all for unsupported or unexpected cases

Prominent Disclosure

Submission to the Google Play store now requires apps to display a prominent disclosure for why the app requires persistent location tracking. By default nudge displays a dialog handling this requirement. If you'd like to customize the disclosure messaging, contact us and we will be happy to assist you.

Location Permission Response

Please note that it is no longer necessary to override onRequestPermissionsResult to pass information back to the nudge library.  This process is now handled internally in the nudge library.

Monitoring for change in Nudge status

If you want, you can register a callback to get notified whenever the status of the Nudge instance changes. To do so, use the NudgeStatusNotifier public interface.

   class myNudgeStatusListener implements Nudge.NudgeStatusNotifier{
       public void onNudgeStatusChange(Boolean active, String status){
           Log.i(TAG, (active ? "Active - " : "Inactive - ") + status);
       }
   }

   internal inner class myNudgeStatusListener : Nudge.NudgeStatusNotifier {
        override fun onNudgeStatusChange(active: Boolean, status: String) {
            Log.i(TAG, (if (active) "Active - " else "Inactive - ") + status)
        }
    }

You can then set the callback using setStatusUpdateCallback() in NudgeBuilder.

private Nudge myNudge = new Nudge.NudgeBuilder()
                            ...
                           .setStatusUpdateCallback(new myNudgeStatusListener())
                            ...

myNudge = Nudge.NudgeBuilder()
            ...
            .setStatusUpdateCallback(myNudgeStatusListener())
            ...

That's it! You can now distribute your app to your users and they'll be registered within the nudge ecosystem. You'll be able to send them notifications through your nudge dashboard!

If you already have Firebase Cloud Messenger installed

If you already use FCM, there's no need to worry! You can still use nudge alongside your existing project. In your FirebaseMessagingService, make sure you import com.larky.nudge.Nudge at the top of the file and add the following line to your onMessageReceived handler.

public void onMessageReceived(RemoteMessage remoteMessage) {
  if (remoteMessage.getData() != null) {
   Map < String, String > data = remoteMessage.getData();
   String isNudge = data.get("isNudge");
    if (Boolean.parseBoolean(isNudge)) {
       Nudge.handlePush(getApplicationContext(), remoteMessage);
       Log.d(TAG, "nudge notification received"); 
    } else { 
       //Your code to handle your non-nudge data notifications 
       Log.d(TAG, "Non-nudge data notification received"); 
    } 
  } 
  //Handle non-data notifications 
  Log.d(TAG, "Non-data notification received"); 
}

override fun onMessageReceived(remoteMessage: RemoteMessage) {
        if (remoteMessage.data != null) {
            val data = remoteMessage.data
            val isNudge = data["isNudge"]
            if (java.lang.Boolean.parseBoolean(isNudge)) {
                Nudge.handlePush(getApplicationContext(), remoteMessage)
                Log.d(TAG,"nudge notification received")
            }
            else {
                //Your code to handle your non-nudge data notifications
                Log.d(TAG, "Non-nudge data notification received")
            }
        }
        //Handle non-data notifications
        Log.d(TAG,"Non-data notification received")
    }

Deprecated Firebase APIs

Also, we have found that developers may have problems getting the correct token if they implement the deprecated service FirebaseInstanceIDService or method getToken(). Please only use the FirebaseMessagingService method onNewToken() to check for new tokens. 

If you're having trouble retrieving the correct token for other Firebase project(s), this is likely the source of the problem.