Getting Started

Requirements

iOS 8.0+
Xcode 9.2 (Swift 4.0.2)
Register for a predict.io API key

Installation (CocoaPods)

Installation via CocoaPods can be accomplished by adding one of the following to your Podfile:

pod 'PredictIO', '~> 5.2.0'

Installation (Carthage)

Add this to your Cartfile:

github "predict-io/PredictIO-iOS" ~> 5.2.0

And install...

$ carthage update --platform iOS  --cache-builds

Link Binary with Libraries

Link your app with the following System Frameworks:

AdSupport.framework
CoreLocation.framework
CoreMotion.framework
Foundation.framework
SystemConfiguration.framework
libsqlite3.tbd
libz.tbd

Once you've run the previous Carthage command you can add the SDK and its dependencies to your app also:

PredictIO.framework
RxSwift.framework
SwiftyJSON.framework

Add 'Copy Frameworks' Build Phase

Create a 'New Run Script Phase' with the following contents:

/usr/local/bin/carthage copy-frameworks

Under Input Files add an entry for each of the following items:

$(SRCROOT)/Carthage/Build/iOS/PredictIO.framework
$(SRCROOT)/Carthage/Build/iOS/RxSwift.framework
$(SRCROOT)/Carthage/Build/iOS/SwiftyJSON.framework

Usage

Configure your project

1. Enable Background Location Updates

Location is used efficiently while in the background, having minimal effect on battery usage. To enable Background Location Updates open your Project Settings, select your App Target, choose Capabilities, enable Background Modes and check Location updates.

NOTE You are required to handle the location permissions request in your application with your own implementation.

2. App Usage Descriptions to `Info.plist`

iOS requires you provide the user with a meaningful description of why you will be using their location. It's required that you add the following to your Info.plist:

Privacy - Location Always Usage Description (NSLocationAlwaysUsageDescription)
For iOS 11+ Privacy - Location Always and When In Use Usage Description (NSLocationAlwaysAndWhenInUseUsageDescription)

Integrate the SDK

NOTE: The SDK start() method must be called always when your app is launched (from background or foreground launch); a good place to do this would be in your AppDelegate, in the func applicationDidFinishLaunching(_ application: UIApplication) or func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool methods.

// Import the SDK in your AppDelegate
import PredictIO

let apiKey = "<YOUR_API_KEY>"

PredictIO.start(apiKey: "") { (error) in
  switch error {
  case .invalidKey?:
    // Your API key is invalid (incorrect or deactivated)
    print("Invalid API Key")
    
  case .killSwitch?:
    // Kill switch has been enabled to stop the SDK
    print("Kill switch is active")

  case .wifiDisabled?:
    // User has WiFi turned off significantly impacting location accuracy available.
    // This may result in missed events!
    // NOTE: SDK still launches after this error!
    print("WiFi is turned off")

  case .locationPermissionNotDetermined?:
    // Background location permission has not been requested yet.
    // You need to call `requestAlwaysAuthorization()` on your
    // CLLocationManager instance where it makes sense to ask for this
    // permission in your app.
    print("Location permission: not yet determined")

  case .locationPermissionRestricted?:
    // This application is not authorized to use location services.  Due
    // to active restrictions on location services, the user cannot change
    // this status, and may not have personally denied authorization
    print("Location permission: restricted")

  case .locationPermissionWhenInUse?:
    // User has only granted 'When In Use' location permission, and
    // with that it is not possible to determine trips which are made.
    print("Location permission: when in use")

  case .locationPermissionDenied?:
    // User has flat out denied to give any location permission to
    // this application.
    print("Location permission: denied")

  case nil:
    // No error, SDK started with no problems
    print("Successfully started PredictIO SDK!")
  }
}

Webhooks

You can set a webhook URL which you can also receive a copy of the events generated by the predict.io SDK to your own servers. To use this functionality, include code like the following in your app.

PredictIO.setWebhookURL("https://api.yourapp.com/webhook")

Support

Visit our Help Center, open an Issue or send an email to support@predict.io.

Tsole/PredictIO-iOS