To help with React Native development, we've put together a [React Native module](https://www.npmjs.com/package/@foursquare/pilgrim-sdk-react-native). In conjunction with a [sample React Native app](https://github.com/foursquare/RNPilgrimSample) and our [iOS](https://docs.foursquare.com/developer/docs/ios) and [Android](https://docs.foursquare.com/developer/docs/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](https://foursquare.com/contact-us) if you have not signed up for access. ## 1\. Install the Module 1. Install the module NPMYarn ```text npm install @foursquare/pilgrim-sdk-react-native ``` ```text yarn add @foursquare/pilgrim-sdk-react-native ``` 2. Link native code **With [autolinking](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md) (react-native 0.60+)** ```text cd ios && pod install && cd .. ``` **Pre 0.60** ```text react-native link @foursquare/pilgrim-sdk-react-native ``` ## 2\. Configure iOS Implementation 1. Add the following line to the `application:didFinishLaunchingWithOptions` method in your project's `AppDelegate.m` file: ```swift [[FSQPPilgrimManager sharedManager] configureWithConsumerKey:@"CONSUMER_KEY"\n secret:@"CONSUMER_SECRET"\n delegate:nil\n completion:nil]; ``` > Don't forget to use your actual `CONSUMER_KEY` and `CONSUMER_SECRET`, which can be retrieved from your [Foursquare Developer Console](https://foursquare.com/developers/apps). For example: ```swift // AppDelegate.m #import "AppDelegate.h" #import #import #import #import @implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [[FSQPPilgrimManager sharedManager] configureWithConsumerKey:@"CONSUMER_KEY"\n secret:@"CONSUMER_SECRET"\n delegate:nil\n 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. 2. Ensure the `CFBundleIdentifier` of your project's `Info.plist` is correctly added to your Foursquare [Developer Console](https://foursquare.com/developers/apps/) app's iOS Bundle IDs setting. For more details on how to set this up, please refer to Pilgrim's [iOS Getting Started Guide](https://docs.foursquare.com/developer/docs/ios-getting-started#1-register-app-bundle-id). 3. (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`: ```swift [[FSQPPilgrimManager sharedManager] configureWithConsumerKey:@"CONSUMER_KEY"\n secret:@"CONSUMER_SECRET"\n delegate:self\n completion:nil]; ``` and add the notification handlers to your `AppDelegate`: ```swift - (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 *)geofenceEvents { // Handle a geofence event } ``` ## 2\. Configure Android Implementation 1. Add the following lines to the `onCreate` method in your project's `android.app.Application` subclass: ```java PilgrimSdk.Builder builder = new PilgrimSdk.Builder(this) .consumer("CONSUMER_KEY", "CONSUMER_SECRET") .enableDebugLogs(); PilgrimSdk.with(builder); ``` For example: ```java // 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. 2. In `android/app/build.gradle` modify the `signingConfigs` section to use your keystore file and ensure the `storePassword`, `keyAlias`, and `keyPassword` are set correctly: ```text signingConfigs { debug { storeFile file('/path/to/file.keystore') storePassword 'storePassword' keyAlias 'keyAlias' keyPassword 'keyPassword' } } ``` 3. Ensure the `SHA1` key hash of your project is correctly added to your Foursquare [Developer Console](https://foursquare.com/developers/apps/) app's Android Key Hashes setting. For more details on how to set this up, please refer to Pilgrim's [Android Getting Started Guide](https://docs.foursquare.com/developer/docs/android-getting-started#1-register-your-apps-key-hashes). 4. (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`: ```java 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 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: ```java 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.