Get Started

To help with React Native development, we've put together a React Native module. In conjunction with a sample React Native app and our iOS and Android docs, you should have everything you need to get up and running.

Note: This article was last updated on Dec 13, 2019 and tested with React Native 0.61.

🚧
PREREQUISITES
In order to implement the Pilgrim SDK in your app, you must first complete the following:

Foursquare Developer Account w/ ClientID + Secret

Pilgrim Access Enabled

Please Contact Us if you have not signed up for access.

1. Install the Module

Install the module

npm install @foursquare/pilgrim-sdk-react-native

yarn add @foursquare/pilgrim-sdk-react-native

Link native code

With autolinking (react-native 0.60+)

cd ios && pod install && cd ..

Pre 0.60

react-native link @foursquare/pilgrim-sdk-react-native

2. Configure iOS Implementation

Add the following line to the application:didFinishLaunchingWithOptions method in your project's AppDelegate.m file:

[[FSQPPilgrimManager sharedManager] configureWithConsumerKey:@"CONSUMER_KEY"
                                                           secret:@"CONSUMER_SECRET"
                                                         delegate:nil
                                                       completion:nil];

Don't forget to use your actual CONSUMER_KEY and CONSUMER_SECRET, which can be retrieved from your Foursquare Developer Console.

For example:

// AppDelegate.m
   #import "AppDelegate.h"

   #import <React/RCTBridge.h>
   #import <React/RCTBundleURLProvider.h>
   #import <React/RCTRootView.h>
   #import <Pilgrim/Pilgrim.h>

   @implementation AppDelegate

   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
   {
     [[FSQPPilgrimManager sharedManager] configureWithConsumerKey:@"CONSUMER_KEY"
                                                           secret:@"CONSUMER_SECRET"
                                                         delegate:nil
                                                       completion:nil];
      // Other react native initialization code

      return YES;
    }
    ...

This allows Pilgrim to run in the background and send you visit notifications, even when your iOS app isn't open.

Ensure the CFBundleIdentifier of your project's Info.plist is correctly added to your Foursquare Developer Console app's iOS Bundle IDs setting. For more details on how to set this up, please refer to Pilgrim's iOS Getting Started Guide.
(Optional) If you want to handle Pilgrim background notifications locally on the device, you would need to set the configureWith method's delegate to self:

[[FSQPPilgrimManager sharedManager] configureWithConsumerKey:@"CONSUMER_KEY"
                                                         secret:@"CONSUMER_SECRET"
                                                       delegate:self
                                                     completion:nil];

and add the notification handlers to your AppDelegate:

- (void)pilgrimManager:(FSQPPilgrimManager *)pilgrimManager handleVisit:(FSQPVisit *)visit {
       // Handle a visit
   }

   - (void)pilgrimManager:(FSQPPilgrimManager *)pilgrimManager handleBackfillVisit:(FSQPVisit *)visit {
       // Handle a backfilled Visit
   }

   - (void)pilgrimManager:(FSQPPilgrimManager *)pilgrimManager handleGeofenceEvents:(NSArray<FSQPGeofenceEvent *> *)geofenceEvents {
       // Handle a geofence event
   }

2. Configure Android Implementation

Add the following lines to the onCreate method in your project's android.app.Application subclass:

PilgrimSdk.Builder builder = new PilgrimSdk.Builder(this)
           .consumer("CONSUMER_KEY", "CONSUMER_SECRET")
           .enableDebugLogs();
   PilgrimSdk.with(builder);

Don't forget to use your actual CONSUMER_KEY and CONSUMER_SECRET, which can be retrieved from your Foursquare Developer Console.

For example:

// MainApplication.java
   import android.app.Application;
   import com.facebook.react.ReactApplication;
   import com.foursquare.pilgrim.PilgrimSdk;

   public class MainApplication extends Application implements ReactApplication {

       @Override
     public void onCreate() {
       super.onCreate();

       PilgrimSdk.Builder builder = new PilgrimSdk.Builder(this)
               .consumer("CONSUMER_KEY", "CONSUMER_SECRET")
               .enableDebugLogs();
       PilgrimSdk.with(builder);

       // Other react native initialization code
     }

     ...

   }

This allows Pilgrim to run in the background and send you visit notifications, even when your Android app isn't open.

In android/app/build.gradle modify the signingConfigs section to use your keystore file and ensure the storePassword, keyAlias, and keyPassword are set correctly:

signingConfigs {
     debug {
       storeFile file('/path/to/file.keystore')
       storePassword 'storePassword'
       keyAlias 'keyAlias'
       keyPassword 'keyPassword'
     }
   }

Ensure the SHA1 key hash of your project is correctly added to your Foursquare Developer Console app's Android Key Hashes setting. For more details on how to set this up, please refer to Pilgrim's Android Getting Started Guide.
(Optional) If you want to handle Pilgrim background notifications locally on the device, you will need to add the notification handlers to your Application's onCreate:

private final PilgrimNotificationHandler pilgrimNotificationHandler = new PilgrimNotificationHandler() {
       // Primary visit handler
       @Override
       public void handleVisit(Context context, PilgrimSdkVisitNotification notification) {
           // Process the visit however you'd like:
           //Visit visit = notification.getVisit();
           //Venue venue = visit.getVenue();
           //Log.d("PilgrimSdk", visit.toString());
       }

       // Optional: If visit occurred while in Doze mode or without network connectivity
       @Override
       public void handleBackfillVisit(Context context, PilgrimSdkBackfillNotification notification) {
           // Process the visit however you'd like:
           //super.handleBackfillVisit(context, notification);
           //Visit visit = notification.getVisit();
           //Venue venue = visit.getVenue();
           //Log.d("PilgrimSdk", visit.toString());
       }

       // Optional: If visit occurred by triggering a geofence
       @Override
       public void handleGeofenceEventNotification(Context context, PilgrimSdkGeofenceEventNotification notification) {
           // Process the geofence events however you'd like:
           //List<GeofenceEvent> geofenceEvents = notification.getGeofenceEvents();
           //for (GeofenceEvent geofenceEvent : geofenceEvents) {
           //  Log.d("PilgrimSdk", geofenceEvent.toString());
           //}
       }
   };

and update the Pilgrim configuration in your onCreate to include the notification handler. For example:

PilgrimSdk.Builder builder = new PilgrimSdk.Builder(this)
           .consumer("CLIENT_ID", "CLIENT_SECRET")
           .notificationHandler(pilgrimNotificationHandler)
           .enableDebugLogs();
   PilgrimSdk.with(builder);

Why? Pilgrim handles location events in the background without the requirement of any visible UI. React Native, being written in JS, requires a UI thread before it is able to properly run. Adding the code to handle Pilgrim at the native Java level, allows Pilgrim to still run in the background.

🚧PREREQUISITES

1. Install the Module

2. Configure iOS Implementation

2. Configure Android Implementation

🚧
PREREQUISITES