### PREREQUISITES

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

- **[Movement SDK Access Enabled](https://docs.foursquare.com/developer/docs/movement-sdk-get-started)**
- **Foursquare Developer Account w/ ClientID + Secret**

## 1. Register App Bundle ID

In order for the Movement SDK to authenticate with our server, you'll need to add your iOS Bundle ID to your Foursquare app's configuration.

1. Navigate to your [Foursquare Developer Console](https://foursquare.com/developers/apps/) and select your app, then:
2. Find your app's **Bundle Identifier**. This can be found in the **Identity** section of your project's **General** tab:

3. In your Foursquare Developer Console on the **Movement SDK Settings** page, paste your iOS Bundle ID in the **iOS Bundle IDs** field.

**Note:** you can add multiple bundle IDs delimited by commas.

4. Save your changes.

## 2. Install the Movement SDK

### Option 1 - Carthage

1. Add the following to your `Cartfile`:

```text
binary "https://foursquare.jfrog.io/foursquare/movementsdk-ios/MovementSdk.json" ~> 4.0.0
```

2. Navigate to **Carthage/Build/iOS** and drag the `MovementSdk.framework` file into Xcode in the **Link Binary With Libraries** section.

3. Add a run script with the following script: `/usr/local/bin/carthage copy-frameworks`

4. Set the **Input Files** to: `$(SRCROOT)/Carthage/Build/iOS/MovementSdk.framework`

5. Load the MovementSDK library into any necessary files by adding `import MovementSdk`.

6. Build your project.

### Option 2 - CocoaPods

1. If you don't already have CocoaPods initiated in your project, enter the following command into the terminal: `pod init`

2. Add the following to your **Podfile**:

```text
pod 'MovementSdk', '~> 4.0.1'
```

3. Enter the following command into the terminal: `pod install` (If you experience errors, try `pod update`.)

4. Load the MovementSDK library into any necessary files by adding `import MovementSdk`.

5. Build your project.

### Option 3 - Swift Package Manager

1. In Xcode, install the Movement SDK by navigating to **File > Add Packages…**  
2. In the prompt that appears, search for the Movement SDK with the following Package URL: `https://github.com/foursquare/movementsdk-ios-spm`  
3. Select the version of the Movement SDK you want to use. For new projects, we recommend using the newest version of the Movement SDK.

## 3. Configure the Movement SDK

### a. Configure Permissions

1. Turn **Background Modes** to **On** in your project's **Capabilities** tab and enable the **Location updates** checkbox:

2. 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

### b. Configure your AppDelegate

Configure the Movement SDK 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.

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

If you are leveraging the Movement SDK in conjunction with the [Personalization API](https://docs.foursquare.com/developer/reference/places-api-overview), include `oauthToken` parameter also:

```swift
MovementSdkManager.shared().configure(withConsumerKey: "CLIENT_ID", secret: "CLIENT_SECRET", oauthToken: "OAUTH_TOKEN", delegate: self, completion: nil)
```

### c. Disable AdId transmission

If you're using the free tier or do not have a data sharing agreement, you don't need to transmit the phone's mobile AdId to Foursquare:

```swift
# before the configure call:
MovementSdkManager.shared().disableAdIdentitySharing = true
```

### d. Conform to the Movement SDK Delegate

Have your **AppDelegate** conform `MovementSdkManagerDelegate` by pasting the following code:

```swift
extension AppDelegate : MovementSdkManagerDelegate {
  func movementSdkManager(_ movementSdkManager: MovementSdkManager, handle visit: Visit) {
    print("(visit.hasDeparted ? "Departure from" : "Arrival at") (visit.venue != nil ? visit.venue!.name : "Unknown venue."). Added an SDK visit at: (visit.displayName)")
  }
  func movementSdkManager(_ movementSdkManager: MovementSdkManager, handleBackfill visit: Visit) {
    print("Backfill (visit.hasDeparted ? "departure from" : "arrival at") (visit.venue != nil ? visit.venue!.name : "Unknown venue."). Added an SDK backfill visit at: (visit.displayName)")
  }
  func movementSdkManager(_ movementSdkManager: MovementSdkManager, handle geofenceEvents: [GeofenceEvent]) {
    geofenceEvents.forEach { geofenceEvent in
      print(geofenceEvent)
    }
  }
  func movementSdkManager(_ movementSdkManager: MovementSdkManager, handleUserState updatedUserState: UserState, changedComponents: UserStateComponent) {
    switch changedComponents {
    case .city:
      print("Welcome to (updatedUserState.city)")
    }
  }
  func movementSdkManager(_ movementSdkManager: MovementSdkManager, handle error: Error) {
    print(error)
  }
}
```

## 4. Initialize the Movement SDK

Once the SDK is configured and set up to handle location events, you need to request location permissions from your user and tell the SDK to start running by calling `start` when `.authorizedAlways`:

```swift
MovementSdkManager.shared().start()
```

**Note:** You must inform the user of how you are using these permissions and how it benefits them.

### a. Request Foreground Location

The SDK allows you to actively request the device's current location manually when the app is in use:

```swift
MovementSdkManager.shared().getCurrentLocation { (currentLocation, error) in
   // Example: currentLocation.currentPlace.venue.name
}
```

## Optional Configurations

### Adding Wifi Entitlement

As of iOS 13.0, the Movement SDK must be configured to access Wifi information via the Wifi Entitlement.

#### 1. Editing the app configuration 
Go to the [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources) portal on the Apple Developer site, then click on Identifiers, then select the app identifier you want to add the Wifi Entitlement to.

#### 2. Regenerate provisioning profiles
Still on the Certificates, Identifiers & Profiles portal, click on Profiles to list the provisioning profiles, you will need to regenerate any profile that was created for the app identifier updated in the previous step.

#### 3. Update the app in Xcode
In Xcode, open the preferences pane (Xcode > Preferences) then select Accounts. Select your Apple ID and team, then click Download Manual Profiles. In Xcode's Signing and Capabilities pane, select `+ Capability` and double click on `Access Wifi Information`. This will add the `com.apple.developer.networking.wifi-info` key to your Entitlements plist file.