Getting Started

Requirements

• iOS 8.0+
• Xcode 9.3 (Swift 4.1)
• 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.5.0'

Installation (Carthage)

Add this to your Cartfile:

github "predict-io/PredictIO-iOS" ~> 5.5.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:

1. PredictIO.framework
2. RxSwift.framework
3. 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:

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

Usage

Configure your project

Enable Background Location Updates (High Power mode only*)

NOTE *You only need to do this if you use High Power mode otherwise it can be skipped

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.

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: "") { (status) in
  switch status {
  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 .success:
    // No error, SDK started with no problems
    print("Successfully started PredictIO SDK!")
  }
}

High Power & Low Power

The predict.io SDK comes in two power levels which cater to different requirements of battery consumption and latency of events being detected.

NOTE: Power level won't take effect properly until a fresh app relaunch, it's not a setting which should be toggled at runtime.

High Power

• 5% typical battery usage in 24 hour period
• Events detected within a few minutes
• Mode of Transport detection (coming soon in future beta)
• Intention detection (coming soon in future beta)

PredictIO.start(apiKey: apiKey, powerLevel: .highPower) {
  error in
  // Handled as above
}

Low Power

• Less than 1% typical battery usage in 24 hour period
• Events detected with up to 30 min delay
• No Mode of Transport detection
• Intention detection (coming soon in future beta)

NOTE: Low power is the default if no value is set for the powerLevel parameter.

PredictIO.start(apiKey: apiKey, powerLevel: .lowPower)

Events

The predict.io SDK can give you callbacks for the events which are detected for you to integrate with your own app's functionality.

PredictIO.notify(on: .any) {
  (event: PredictIOTripEvent) in
  // Do something with event 
}

PredictIO.notify(on: .departure) {
    event in
    // Do something when user has left a location
}

PredictIO.notify(on: .arrival) {
    event in
    // Do something when user has arrived at a location
}

PredictIOTripEvent

A PredictIOTripEvent is the event you will receive that describes attributes of the event which was detected, namely; the location, timestamp and type of the event from the following:

• .arrival
• .departure
• .enroute (High Power only)
• .still (High Power only)

public class PredictIOTripEvent: CustomStringConvertible {
  public let type: PredictIOTripEventType
  public let coordinate: CLLocationCoordinate2D
  public let timestamp: Date
}

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.start(apiKey: "<YOUR API KEY>") {
//   error in
// }...

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

Pre-flight Checklist

1. Register for a predict.io API key
2. Request the 'Always' location permission in your app; our SDK doesn't request location permission automatically!
3. Integrate the SDK snippet into your app to start the SDK
4. Optionally, integrate the webhooks
5. Handle the callback events
6. When submitting your app, select the following options for the section Advertising Identifier:
   • Does this app use the Advertising Identifier (IDFA)? Yes
   • Serve advertisements within the app? Our SDK DOES NOT serve adds (choose what's appropriate for your app)
   • Attribute this app installation to a previously served advertisement Yes
   • Attribute an action taken within this app to a previously served advertisement Yes

Support

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