This tutorial will walk you through the steps of using the Ride Request API in your iOS app. In this guide, we’ll be going through the entire process to get a working app with the Rides SDK configured. We will set up and configure the SDK, then walk through an example Ride Request integration.

¶ Your iOS Project

We can create a new Single View Application project to demonstrate how to begin using the SDK. In XCode, choose File > New > Project and when prompted to “Choose a template for your new project”, select Single View Application and click Next.

In the next screen, set the Product Name field to any name you want, leave everything else as the default and click Next. Choose which folder you want to save the project to and click Create. You now have a boilerplate app with just one view!

¶ Add the SDK to your project

There are currently two ways to add the Uber Rides iOS SDK to your project:

• CocoaPods
• Carthage

Using a dependency manager such as Carthage or CocoaPods makes it easy to keep your app updated with the latest version of the SDK.

¶ CocoaPods

The Uber Rides iOS SDK is a CocoaPod written in Swift. You can install CocoaPods with the following command:

$ gem install cocoapods

To integrate Uber Rides into your Xcode project, navigate to the directory that contains your project and create a new Podfile with pod init. Add the following under your Podfile’s target:

target 'Your Project Name' do
  use_frameworks!
  pod 'UberRides', '~> 0.9'
end

Then, run the following command to install the dependency:

$ pod install

Next, close your Xcode project. In your project folder, you should see another file alongside your .xcodeproj file: the .xcworkspace file. Open the .xcworkspace file.

Congratulations, you’ve added the Uber Rides iOS SDK into your project using CocoaPods! Next, you have to configure the sdk.

¶ Carthage

You can integrate Uber Rides into your project using Carthage. You can install Carthage (with XCode 7+) via homebrew:

brew update
brew install carthage

To install UberRides via Carthage, you need to create a Cartfile. In the root directory of your project, run the following command:

touch Cartfile

In the editor of your choice open the file and add the following:

# UberRides
github "uber/rides-ios-sdk" ~> 0.9

Now run the following command to checkout & build our repo and dependencies.

carthage update --platform iOS

You should now have a Carthage/Build folder in your project directory. Open your .xcodeproj and go to the General settings tab. In the Linked Frameworks and Libraries section, drag and drop each framework (in Carthage/Build/iOS)

Now, open your application target’s Build Phases settings tab, click the + icon, and select New Run Script Phase. Add the following to the script area:

/usr/local/bin/carthage copy-frameworks

and add the paths to the required frameworks in Input Files

$(SRCROOT)/Carthage/Build/iOS/UberRides.framework

Congratulations, you’ve added the Uber Rides iOS SDK into your project using Carthage! Next, you have to configure the sdk.

¶ Configuring the SDK

To begin making calls to the Uber API, you need to register an application on the Uber Developer Site and get credentials for your app.

Then, configure your Xcode with information for the Uber SDK. Locate the Info.plist file for your application. Right-click this file and select Open As > Source Code

Add the following code snippet, replacing the placeholders within the square brackets ([]) with your app’s information from the developer dashboard. (Note: Do not include the square brackets)

<key>UberClientID</key>
<string>[ClientID]</string>
<key>UberDisplayName</key>
<string>[App Name]</string>
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>uber</string>
    <string>uberauth</string>
</array>

¶ Setup

To use any of the SDK’s other features, you need to have the end user authorize your application to use the Uber API.

First, open up the Uber Developer Dashboard. Go to the Settings tab and put in your iOS application’s Bundle ID in the App Signatures field.

We also need to register a Redirect URL for your application. This ensures that Uber sends users to the correct application after they log in. Make a URL in this format, and save your application: YourApplicationBundleID://oauth/consumer.

In your Xcode project, you need to register your URL scheme as well as the callback URL with the Uber SDK. Copy this into your Info.plist, replacing the relevant values:

<key>UberCallbackURIs</key>
<array>
    <dict>
        <key>UberCallbackURIType</key>
        <string>General</string>
        <key>URIString</key>
        <string>[Your Bundle ID Here]://oauth/consumer</string>
    </dict>
</array>
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>[Your Bundle ID Here]</string>
        </array>
    </dict>
</array>

You also need to modify your application’s App Delegate to make calls to the RidesAppDelegate to handle URLs.

// Swift
// Add the following calls to your AppDelegate
import UberCore
    
@available(iOS 9, *)
func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any]) -> Bool {
    let handledUberURL = UberAppDelegate.shared.application(app, open: url, sourceApplication: options[UIApplicationOpenURLOptionsKey.sourceApplication] as? String, annotation: options[UIApplicationOpenURLOptionsKey.annotation] as Any)

    return handledUberURL
}
    
func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
    let handledUberURL = UberAppDelegate.shared.application(application, open: url, sourceApplication: sourceApplication, annotation: annotation)

    return handledUberURL
}

// Objective-C
// Add the following calls to your AppDelegate
@import UberCore;

// iOS 9+
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *,id> *)options {
    BOOL handledURL = [[UBSDKAppDelegate shared] application:app open:url sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey] annotation:options[UIApplicationOpenURLOptionsAnnotationKey]];
    
    return handledURL;
}

// iOS 8
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    BOOL handledURL = [[UBSDKAppDelegate shared] application:application open:url sourceApplication:sourceApplication annotation:annotation];
    
    return handledURL;
}

¶ Login with Uber (SSO)

Single Sign On is a way to authorize users using the native Uber application. If your users are already logged in on the Uber app, they won’t have to enter a username and password to authorize your app.

To begin the process, we instantiate a LoginManager which will handle the login session. We call the login method and request scopes, or permissions, to ineract with the user account. In this scenario, we want to make ride requests on the user behalf, so we’ll request the request scope. See more about available scopes

We’ll recieve a callback with the access token, and it will be automatically stored for future API calls.

// Swift
let loginManager = LoginManager()
loginManager.login(requestedScopes:[.request], presentingViewController: self, completion: { accessToken, error in
    // Completion block. If accessToken is non-nil, you’re good to go
    // Otherwise, error.code corresponds to the RidesAuthenticationErrorType that occured
})

// Objective-C
UBSDKLoginManager *loginManager = [[UBSDKLoginManager alloc] init];
[loginManager loginWithRequestedScopes:@[ UBSDKRidesScope.request ] presentingViewController: self completion: ^(UBSDKAccessToken * _Nullable accessToken, NSError * _Nullable error) {
    // Completion block. If accessToken is non-nil, you're good to go
    // Otherwise, error.code corresponds to the RidesAuthenticationErrorType that occured
}];

¶ Ride Requests

The Uber API gives you the ability to Request an Uber Product on behalf of users within your application. Given you know where a user currently is, where they want to go, and which Uber product they want to use to get there, you have all of the tools to make that happen with a few simple API endpoints.

1. In the products endpoint GET /products, products will have the upfront_fare_enabled field set to true.
2. Use the request estimate endpoint POST /requests/estimate with the product_id to get a fare_id. The fare_id can be used to lock down an upfront fare and arrival time for a trip. The fare_id expires after two minutes. If the fare_id is expired or not valid, we return a 422 error.
3. Request the ride using the request endpoint POST /requests with the fare_id returned in the previous step.

¶ The Sandbox

Because of the real-world nature of the Ride Request endpoints, which call active drivers on the system which result in financial transactions on Uber rider accounts, the Uber API provides a sandbox environment for testing. All ride requests made to the sandbox will result in a simulated ride request that can be programmatically updated. To get an understanding on how to set up your environment for making ride requests within the sandbox environment, see the sandbox guide.

¶ Request a Ride

let ridesClient = RidesClient()
let pickupLocation = CLLocation(latitude: 37.787654, longitude: -122.402760)
let dropoffLocation = CLLocation(latitude: 37.775200, longitude: -122.417587)
let builder = RideParametersBuilder()
builder.pickupLocation = pickupLocation
builder.dropoffLocation = dropoffLocation

ridesClient.fetchProducts(pickupLocation: pickupLocation) { products, response in
    guard let uberX = products.filter({$0.productGroup == .uberX}).first else {
        // Handle error, UberX does not exist at this location
        return
    }
    builder.productID = uberX.productID
    ridesClient.fetchRideRequestEstimate(parameters: builder.build(), completion: { rideEstimate, response in
        guard let rideEstimate = rideEstimate else {
            // Handle error, unable to get an ride request estimate
            return
        }
        builder.upfrontFare = rideEstimate.fare
        ridesClient.requestRide(parameters: builder.build(), completion: { ride, response in
            guard let ride = ride else {
                // Handle error, unable to request ride
                return
            }
            // Ride has been requested!
        })
    })
}

As a Request is ongoing, you will want to display the details of the Request to the user in a way that helps them understand what is happening and give them the information they need to find or get in touch with their driver. You can do this via either the current rides endpoint, or by registering your backend with a webhook.

ridesClient.fetchCurrentRide { ride, response in
    // Update app based on current app info
}

For instance, when a Request is processing it’s probably best to let the user know Uber is attempting to find them a driver. Using a spinner or other loading indicator can convey this message well.

Once a Request status has changed to accepted you can let your user know a vehicle is enroute, what the details of the driver are, and remind them their pickup location. You can even show them the location of the vehicle on a map because the Uber API provides this location information.

If the Request status becomes arriving you probably want to indicate this to the user in a way that gets their attention. And once a Request is in_progress you can provide the information a user might find useful once they are already in the vehicle.

Unfortunately, there are some times when a driver must cancel a Request, and your application should let the user know when this happens. This will be indicated when the status of a Request is returned as driver_canceled. At this point it’s usually helpful to make it easy for a user to re attempt a Request.

Lastly, sometimes a user needs to get in touch with a driver to clarify their location, so please provide an easy way to call or SMS the driver from within your application.

The possible values for status are:

Status	Description
processing	The Request is matching to the most efficient available driver.
no_drivers_available	The Request was unfulfilled because no drivers were available.
accepted	The Request has been accepted by a driver and is “en route” to start location.
arriving	The driver has arrived or will be shortly.
in_progress	The Request is “en route” from the start location to the end location.
driver_canceled	The Request has been canceled by the driver.
rider_canceled	The Request canceled by
completed	Request has been completed by the driver.

Check out our detailed guide for best practices implementing ride requests for your users.