iOS Install

Don’t use CocoaPods? Get the manual instructions here.

Minumum Operating System

8.0+

Get API keys

If you do not have a Foursquare API key whitelisted for Pilgrim access, read our guide on Foursquare API Access.

Set up your Foursquare App

In order for Pilgrim SDK to authenticate with our server, you’ll need to add your iOS Bundle Id to your Foursquare app’s configuration. This can be found in your project’s General tab:

Navigate to your Foursquare app settings page here: foursquare.com/developers/app/CLIENT_ID

  1. Near the bottom of the page, under Install options, paste your iOS Bundle Id in the iOS Bundle IDs field.
  2. Click Save changes.


Set Up Cocoapods

In order to use CocoaPods, you will need to install the cocoapods-art plugin. To install cocoapods-art, run the following command:

repo-art uses authentication as specified in your standard netrc file. Create the netrc file in your home directory:

Then, add the your login credentials using your text editor:

To add the Pilgrim specs repo, run the following command:

To resolve pods from the Pilgrim specs repo you added, you must add the following to your Podfile:

Then, you can use install as usual:


Permissions

Make sure to turn Background Modes to On in your project’s Capabilities tab and enable the Location updates checkbox:

Add the following to your iOS permission strings in your project’s Info.plist file:

  • Privacy - Location Always Usage Description
  • Privacy - Location Always and When In Use Usage Description
  • Privacy - Location When In Use Usage Description

For example:


Configure and Start Pilgrim

1. Configure Pilgrim in your AppDelegate

Configure Pilgrim by pasting the following code in the didFinishLaunchingWithOptions method of your AppDelegate. Be sure to replace CLIENT_ID and CLIENT_SECRET with your real API credentials.

PilgrimManager.shared().configure(withConsumerKey: "CLIENT_ID", secret: "CLIENT_SECRET", delegate: self, completion: nil)

2. Conform to Pilgrim Delegate

Have your AppDelegate conform PilgrimManagerDelegate by pasting the following code just below your AppDelegate class:

extension AppDelegate : PilgrimManagerDelegate {
    func pilgrimManager(_ pilgrimManager: PilgrimManager, handle visit: Visit) {
        // Process the visit however you like here
    }
}

Note the four delegate callbacks you may receive:

  • handle visit: The primary visit callback that receives arrival and departure events.
  • handleBackfill visit: This callback receives visits that occurred historically when there was no network connectivity or for failed visits that have been retried.
  • handle nearbyVenues: This callback receives any nearby venues that are configured in the Pilgrim console.
  • handle geofenceEvents: This callback receives any genfence events configured in the Pilgrim console.

3. Start Pilgrim

Once Pilgrim is configured, you can start running it by calling start after the configuration method in your AppDelegate:

PilgrimManager.shared().start()

Note: You must make sure the user has accepted background location permissions before starting the SDK. We provide a convenience method for requesting the ‘Always On’ location permission. However, you are not required to use this method.

PilgrimManager.shared().requestAlwaysAuthorization { (authorized) in
            if authorized {
                PilgrimManager.shared().start()
            } else {
                // user rejected location permissions
            }
        }

4. Handle Visits

With Pilgrim properly configured, the delegate method(s) should be hit whenever you arrive or depart at one of our 105M+ places around the world. In order to test your visit callback without physically walking around, we provide a testing class visitTester. This class can be used to simulate visits with different confidence levels and location types.

For example, the following code will simulate a visit at a given lat/lng:

PilgrimManager.shared().visitTester.fireTestVisit(location: CLLocation(latitude: 37.7904311, longitude: -122.4066613))

The following code will trigger a medium confidence arrival at a venue:

PilgrimManager.shared().visitTester.fireTestVisit(confidence: .medium, type: .venue, departure: false)

Tips

Get Current Location

By default, Pilgrim SDK runs in the background and pushes you visits when it detects a stop. You can also actively request the current location manually when the app is in use by calling the below method as a workaround to satisfy our SDK’s ‘Always On’ location permission requirement.

PilgrimManager.shared().getCurrentLocation { (currentLocation, error) in
   // Example: currentLocation.currentPlace.venue.name
}
[[FSQPPilgrimManager sharedManager] getCurrentLocationWithCompletion:^(FSQPCurrentLocation * _Nullable currentLocation, NSError * _Nullable error) {
   // Example: currentLocation.currentPlace.venue.name
}];

This will return the current venue the device is most likely at (in the currentLocation object), as well as any geofences that the device is in (if configured). Note that this foregoes any “stop detection” so it shouldn’t be used as a proxy for visits. For example, this method could return a high confidence result for Starbucks if called while someone is walking by the entrance.


Next Steps

Configuration

Android Install

Minumum Operating System

Android v15+ (ICE_CREAM_SANDWICH_MR1)

Get API keys

If you do not have a Foursquare API key whitelisted for Pilgrim access, read our guide on Foursquare API Access.


Set up your Foursquare App

In order for Pilgrim SDK to authenticate with our server, you’ll need to add your Android Key Hash to your Foursquare app’s configuration. Navigate to your Foursquare app settings page here: foursquare.com/developers/app/CLIENT_ID

  1. Near the bottom of the page, under Install options, paste your Android Key Hash in the Android Key Hashes field.
  2. Click Save changes.


Installation

1. Adding the dependency

Once you have been given a username and password from Foursquare, you can access the repository that has the Pilgrim SDK. Add the following snippet to your root build.gradle file and you will be able to resolve the library.

allprojects {
    repositories {
        maven {
            url 'https://foursquare.jfrog.io/foursquare/libs-release/'
            credentials {
                username 'Provided username'
                password 'Provided password'
            }
        }
    }
}

Then, in the build.gradle file for the project for which you would like to include the Pilgrim SDK, just add:

compile 'com.foursquare:pilgrimsdk:2.1.0'

Configure and Start Pilgrim

1. Configure the Pilgrim SDK

Use the following code to configure the Pilgrim SDK notification handler in your App.java’s onCreate method. Also, you can optionally set the log level to DEBUG to receive more detailed logs while you’re developing and persist them on disk.

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

2. Set up the Pilgrim Notification Handler

In order to be notified of visits, add the Pilgrim SDK notification handlers to your Application’s onCreate method.

private final PilgrimNotificationHandler pilgrimNotificationHandler = new PilgrimNotificationHandler() {
        // Primary visit handler
        @Override
        public void handleVisit(Context context, PilgrimSdkVisitNotification notification) {
            Visit visit = notification.getVisit();
            Venue venue = visit.getVenue();
            // Do something with the place
        }

        // Optional: If visit occured while in Doze mode or without network connectivity
        @Override
        public void handleBackfillVisit(Context context, PilgrimSdkBackfillNotification notification) {
            super.handleBackfillVisit(context, notification);
            Visit visit = notification.getVisit();
            Venue venue = visit.getVenue();
            // Do something with the place
        }

        // Optional: If nearby triggers are configured
        @Override
        public void handleNearbyVenues(Context context, PilgrimSdkNearbyNotification notification) {
            List<NearbyVenue> nearbyPlaces = notification.getNearbyPlaces();
            // Do something with the places
        }

        // Optional: If visit occured by triggering a geofence
        @Override
        public void handleGeofenceEventNotification(Context context, PilgrimSdkGeofenceEventNotification notification) {
          List<GeofenceEvent> geofenceEvents = notification.getGeofenceEvents();
          // Do something with the events
        }
    };

Note the four types of notifications you may receive:

  • handleVisit: The primary visit handler that receives arrival and departure events.
  • handleBackfillVisit: This handler receives visits that occurred when theire was no network connectivity or for failed visits that have been retried. For arrivals, departureTime will be null.
  • handleNearbyVenues: If any nearby triggers are configured, those places will be returned here.
  • handleGeofenceEventNotification: This handler receives visits for geofences.

3. Start Pilgrim

Once Pilgrim is configured, you can start running it by calling PilgrimSdk.start(this); in your MainActivity#onCreate.

PilgrimSdk.start(this);

4. Handle a Visit

With Pilgrim properly configured, the notification handlers hit whenever you arrive or depart one of our 105M+ places around the world. In order to test your visit callback without physically walking around, we provide two test methods:

  • PilgrimNotificationTester.fireTestVisit can test your PilgrimNotificationHandler implementation without moving around.
    void PilgrimNotificationTester.fireTestVisit(
      @NonNull Context context,
      @NonNull Confidence confidence,
      @NonNull LocationType placeType,
      boolean isExit
    )
    
  • PilgrimNotificationTester.sendConnectedTestVisit is an online version of the helper method to test your PilgrimNotificationHandler implementation without moving around. This method communicates with the Foursquare servers and validates that what you pass would generate a visit notification to your app if you were actually there.
    void PilgrimNotificationTester.sendConnectedTestVisit(
      String venueId,
      @NonNull Confidence confidence,
      @NonNull LocationType placeType,
      boolean isExit
    )
    

Tips

Get Current Location

By default, Pilgrim SDK runs in the background and pushes you visits when it detects a stop. You can also actively request the current location manually when the app is in use by calling the PilgrimSdk.get().getCurrentLocation() method.

if (ContextCompat.checkSelfPermission(this, android.Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) {
                new Thread(new Runnable() {
                    @Override
                    public void run() {
                        Result<CurrentLocation, Exception> result = PilgrimSdk.get().getCurrentLocation();
                        if (result.isOk()) {
                            CurrentLocation currentLocation = result.getOrNull();
                            Log.d("PilgrimSdk", "Currently at " + currentLocation.getCurrentPlace().toString() + " and inside " + result.getOrNull().getMatchedGeofences().size() + " geofence(s)");
                        } else {
                            Log.e("PilgrimSdk", result.getErr().getMessage(), result.getErr());
                        }
                    }
                }).start();
            }

This will return the current venue the device is most likely at (in the currentLocation object), as well as any geofences that the device is in (if configured). Note that this will forgo any “stop detection” so it shouldn’t be used as a proxy for visits. For example, this method could return a high confidence result for Starbucks if called while someone is walking by the entrance.

Stop Monitoring Visits

If you need to stop monitoring the user’s visits (for example, if they opt out or turn off your background feature), you can turn off the Pilgrim SDK by calling:

PilgrimSdk.stop(context);

This will stop all Pilgrim activity. To resume Pilgrim, just call start() again. Repeatedly starting and stopping the SDK will temporarily reduce accuracy and drain battery.

Clearing All History

In certain instances, you may want to clear a users visit history entirely from the device, including their Home and Work locations. An example of this may be a user logging out of your app. For this you should use:

PilgrimSdk.clearAllData(context);

Android Permissions

These are the permissions that the SDK will add to your manifest. Please let us know if you have any questions about this list.

    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />

Targeting Android Marshmallow

If you are using targetSdk 23, then you will need to make sure that your app requests the ACCESS_FINE_LOCATION permission. Pilgrim will not run without the location permission. Once your user accepts the location permission, you should call PilgrimSdk.start(context).

public void requestLocationPermission(Activity activity, int requestCode) {
    ActivityCompat.requestPermissions(activity, new String[]{Manifest.permission.ACCESS_FINE_LOCATION},
            requestCode);
}

Next Steps

Configuration