Skip to main content

nudge® Base / nudge® Geo Code Libraries for Android Integration Guide

Dana Haukoos
  • Updated

This guide documents the process for including the nudge® mobile library in an Android application: for an implementation that does not include the optional location-based messaging functionality add-on, follow the instructions in the nudgeBase column; for an implementation that does include the optional location-based messaging functionality add-on, follow the instructions in the nudgeGeo column. 

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

Migrating from the legacy nudge® Plus Code Library

To migrate from the nudge® Plus Code Library to the current architecture of nudge® Base / nudge® Geo see our short guide here.

Library versions

As of this writing the latest libraries are 

nudgeBase nudgeGeo
releases.com.larky:nudgeBase:1.4.0 releases.com.larky:nudgeGeo:1.2.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.3.1
  • Android compileSdkVersion: 35
  • Android minSdkVersion: 21+
  • Google services: 4.3.13
  • In gradle.properties:
    • android.useAndroidX=true
    • android.enableJetifier=true

Note on location permissions [NudgeGeo]

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 libraries

nudgeBase and nudgeGeo are 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).

nudgeBase nudgeGeo 
dependencies { 
  implementation fileTree(dir: 'libs', include: ['*.jar']) 
  implementation 'com.android.support:appcompat-v7:26.1.0' 
  testImplementation 'junit:junit:4.12' 
 // Add this line for NudgeBase 
  implementation 'releases.com.larky:nudgeBase:<LIB_VERSION_NUMBER>'
 }
 
dependencies { 
  implementation fileTree(dir: 'libs', include: ['*.jar']) 
  implementation 'com.android.support:appcompat-v7:26.1.0' 
  testImplementation 'junit:junit:4.12' 
 // Add these two lines for NudgeBase with NudgeGeo
  implementation 'releases.com.larky:nudgeBase:<LIB_VERSION_NUMBER>'
implementation 'releases.com.larky:nudgeGeo:<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

nudgeBase nudgeGeo 
import com.larky.nudgeBase.NudgeBase;
 
import com.larky.nudgeGeo.NudgeGeo;

 

Declare the nudge object

This is usually done at the activity level scope

  nudgeBase nudgeGeo
Java: 
private NudgeBase myNudge;
 
private NudgeGeo myNudge;
Kotlin: 
private var myNudge: NudgeBase? = null
 
private var myNudge: NudgeGeo? = null

 

You can initialize nudge by using NudgeBuilder

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

  nudgeBase nudgeGeo
Java: 
this.myNudge = new NudgeBase.NudgeBuilderBase() 
    .setApplicationContext(getApplicationContext()) 
    .setApiKey("<YOUR_API_KEY_HERE>") 
    .setResourceId(<RESOURCE_ID>) 
    .setStatusUpdateCallback(new MyNudgeStatusNotifier())
    .setUserFederationId(<USERID_ID>) 
    .setEnabled(true) 
    .build();


















































 
myNudge = new NudgeGeo.NudgeBuilderGeo()
  .setActivity(thisActivity)
  .setApiKey("<YOUR_API_KEY_HERE>")
  .setApplicationContext(getApplicationContext())
  .setPersistentNotificationTitle("<Title>")
  .setPersistentNotificationText("<Text>")
  .setResourceId(<RESOURCE_ID>)
  .setStatusUpdateCallback(new NudgeStatusListener())
  .setUserFederationId(<USERID_ID>)
  .setEnabled(true)
  .setDisclosureDialogEnabled(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 NudgeGeo.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 NudgeGeo.LarkyNudgePermissionListener.FOREGROUND_DENIED:
        break;
                                  
      // The library did not prompt for foreground permissions.
      // The library did not prompt for background permissions. 
      case NudgeGeo.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 NudgeGeo.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 NudgeGeo.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 NudgeGeo.LarkyNudgePermissionListener.BACKGROUND_BYPASS: 
        break;
                              
      // Catch all for unsupported or unexpected cases.
      case NudgeGeo.LarkyNudgePermissionListener.DEFAULT: 
        break;
      }
     }).build();
Kotlin: 
myNudge = NudgeBase.NudgeBuilderBase() 
    .setApplicationContext(getApplicationContext) 
    .setApiKey("<YOUR_API_KEY_HERE>") 
    .setResourceId(<RESOURCE_ID>) 
    .setStatusUpdateCallback(MyNudgeStatusNotifier()) 
    .setUserFederationId(<USERID_ID>) 
    .setEnabled(true) 
    .build()

















































 
myNudge = NudgeGeo.NudgeBuilderGeo()
  .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)
  .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. 
     NudgeGeo.LarkyNudgePermissionListener.FOREGROUND_GRANTED -> {
     }
                                  
     // The library prompted the user for foreground permissions
     // and the user denied.
     // The library did not prompt for background permissions.
     NudgeGeo.LarkyNudgePermissionListener.FOREGROUND_DENIED -> {
     }
                                  
     // The library did not prompt for foreground permissions.
     // The library did not prompt for background permissions. 
     NudgeGeo.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.
     NudgeGeo.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.
     NudgeGeo.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.
     NudgeGeo.LarkyNudgePermissionListener.BACKGROUND_BYPASS -> { 
     }
                              
     // Catch all for unsupported or unexpected cases.
     NudgeGeo.LarkyNudgePermissionListener.DEFAULT -> { 
     }
    }
   }).build()

 

Parameters:

nudgeBase nudgeGeo
  • setApplicationContext(Context): Required
  • 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)
  • 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 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 
  • 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

  • setLarkyNudgePermissionListener():  Required  - Provides information on location permission user responses. See below for further details

Location Permission Listener:

A listener is provided to inform you of the status of the foreground/background location permission status.  The results codes are:

  • 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 nudgeGeo 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.

Java:
 
class myNudgeStatusListener 
         implements NudgeBase.NudgeStatusNotifier{
    public void onNudgeStatusChange(Boolean active, 
                                    String status){     
        Log.i(TAG, (active ? "Active - " 
                           : "Inactive - ") + status);
    }
}
Kotlin: 
internal inner class myNudgeStatusListener : 
        NudgeBase.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.

 
nudgeBase
nudgeGeo
Java:
 
private NudgeBase myNudge = new NudgeBase.NudgeBuilderBase()
   ...
   .setStatusUpdateCallback(new myNudgeStatusListener())
    ...
 
private NudgeGeo myNudge = new NudgeGeo.NudgeBuilderGeo()
   ... 
   .setStatusUpdateCallback(new myNudgeStatusListener()) 
   ...
Kotlin: 
myNudge = NudgeBase.NudgeBuilderBase()
    ...
    .setStatusUpdateCallback(myNudgeStatusListener())
    ...
 
myNudge = NudgeGeo.NudgeBuilderGeo()
   ... 
   .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. You just need to edit your onMessageReceived method as follows in your FirebaseMessagingService! Make sure you import com.larky.nudgeBase.NudgeBase at the top of the file.

Java:
 
public void onMessageReceived(RemoteMessage remoteMessage) {
  if (remoteMessage.getData() != null) {
   Map < String, String > data = remoteMessage.getData();
   String isNudge = data.get("isNudge");
    if (Boolean.parseBoolean(isNudge)) {
       NudgeBase.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"); 
}
Kotlin: 
override fun onMessageReceived(remoteMessage: RemoteMessage) {
        if (remoteMessage.data != null) {
            val data = remoteMessage.data
            val isNudge = data["isNudge"]
            if (java.lang.Boolean.parseBoolean(isNudge)) {
                NudgeBase.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.

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk