# Pilgrim SDK

---

Pilgrim is a location intelligence framework by Foursquare Inc.

| Build Status |
| --- |
|  |

## Dependencies

- iOS 8.0+
- Xcode 10.2
- Carthage (latest) - [https://github.com/Carthage/Carthage](https://github.com/Carthage/Carthage)
  - `brew install carthage`
- Swiftlint (latest) - [https://github.com/realm/SwiftLint](https://github.com/realm/SwiftLint)
  - `brew install swiftlint`

### Installation

1. `brew install swiftlint`
2. `carthage bootstrap --use-xcframeworks --platform ios`
3. Run fastlane match (passwords are in 1Password DCX-Mobile vault (FASTLANE_PASSWORD is in `devbeast`, match passwords are in `Match iOS password`):
```
FASTLANE_PASSWORD=# MATCH_PASSWORD=# MATCH_KEYCHAIN_PASSWORD=# bundle exec fastlane run_match
```

## Deployment

For internal releases use the format `vX.X.X-rcX`. External releases should look like `vX.X.X`. **NOTE: Internal releases must have a `-rc` else the framework will be made available to the public!**

You can find more detailed docs on everything that needs to be done for a release on the [wiki](http://wiki.prod.foursquare.com/iOS/release-process-pilgrim).

## Installation

### Carthage

Add the following to your Cartfile where `X.X.X-rcX` refers to the latest internal [release](https://github.com/foursquare/pilgrim-ios-sdk/releases).

```
binary "https://foursquare.jfrog.io/foursquare/foursquare-internal/Pilgrim.json" ~> X.X.X-rcX
```

### CocoaPods

Add the following to your Podfile where `X.X.X-rcX` refers to the latest internal [release](https://github.com/foursquare/pilgrim-ios-sdk/releases).

```
pod 'Pilgrim', '~> X.X.X'
```

### Manual

Download a copy of the internal SDK from [Artifactory](https://foursquare.jfrog.io/foursquare/foursquare-internal/) where `X.X.X-rcX` refers to the latest internal [release](https://github.com/foursquare/pilgrim-ios-sdk/releases).

```
https://foursquare.jfrog.io/foursquare/foursquare-internal/vX.X.X-rcX
```

For more detailed steps take a look at our [Quickstart Guide](https://developer.foursquare.com/docs/pilgrim-sdk/quickstart)

## Getting Started

In the simplest case, you will have your application delegate implement the `FSQPPilgrimManagerDelegate` protocol, configure and start Pilgrim. Note that it is not required to be on the application delegate, but we are using that here as an example.

```
import Pilgrim

class AppDelegate: UIResponder, UIApplicationDelegate, FSQPPilgrimManagerDelegate {
    let consumerKey = "insert here"
    let consumerSecret = "insert here"
    let locationManager = CLLocationManager()

func application(application: UIApplication,
                    didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        FSQPPilgrimManager.sharedManager().configureWithConsumerKey(consumerKey,
            secret: consumerSecret,
            delegate: self,
            completion: nil)

switch CLLocationManager.authorizationStatus() {
        case .authorizedAlways: FSQPPilgrimManager.sharedManager().startMonitoringVisits()
        case .notDetermined: locationManager.requestAlwaysAuthorization()
        default: break
        }

return true
    }

func fsqpPilgrimManager(locationManager: FSQPPilgrimManager, didVisit visit: FSQPVisit) {
        // Process the FSQPVisit here however you like
    }
}
```

Also note that `requestAlwaysAuthorizationWithCompletion` is provided for convenience; you can call `startMonitoringVisits` at any time after you’ve requested location permission, and you are not required to use our convenience method for requesting permission.

## Usage

### Important:

`startMonitoringVisits()` should be called to kickstart the Pilgrim engine when the user is logged into your app, and `stopMonitoringVisits()` when the user is logged out.

### Adding custom Triggers

There are a few different ways to customize the notifications that Pilgrim sends your app and these are done through Triggers.

You can configure you triggers on the developer site. [https://foursquare.com/developers/app/](https://foursquare.com/developers/app/pilgrim). There you will be able to add triggers for places, categories and chains and a different confidence level.

The default Trigger set for the SDK will notify you of all stops at MEDIUM and above.

Also available on the developer site, is the option to change the notification for home and work, and whether or not you are notified on departures.

### Server to server notifications

If you would like to have your visits sent directly to your servers, you can configure an endpoint to be hit on arrival and departure of your users. With the SDK you can specify your own custom parameters that will be sent along with the request. For more information please contact your Technical Account Manager.

### Permissions

You must have UIBackgroundModes `location` and a NSLocationAlwaysUsageDescription in your Info.plist.

You must prompt the user for “Always” location permissions using `CLLocationManager().requestAlwaysAuthorizationWithCompletion()` to request this.

The SDK will take 3 days of running to determine the users home/work location. It’s possible that you won’t want to use notifications before they have a home/work set, and if that is the case you can check the state when you get a notification from the SDK by checking `FSQPPilgrimManager`‘s `hasHomeOrWork` property.

## Provide visit feedback

You may provide feedback on venue visits with `FSQPVisitFeedbackProvider`, which is available through `FSQPPilgrimManager`’s `visitFeedbackProvider` property. A Foursquare venue id can optionally be included to identify a wrongly-flagged venue.

The available feedback options are:

```
public enum FSQPVisitFeedbackProvider : Int {
    case Confirm
    case FalseStop
    case WrongVenue
    case Deny
}
```

Feedback is used to make long-term improvements to our algorithms.