Protocol

INRequestRideIntentHandling

The handler interface for booking a ride for the user.

Declaration

@protocol INRequestRideIntentHandling

Overview

Use the methods of the INRequestRideIntentHandling protocol to resolve, confirm, and handle requests to book a ride using your service. Adopt this protocol in an object of your Intents extension that is capable of initiating the booking process with your service. SiriKit calls the methods of your object to resolve the parameters to your ride-related information and to book the ride upon confirmation by the user.

Ride requests have many items to resolve. You should resolve all options in some manner, but you may omit options that are not relevant to your service. For example, if your service transports cargo instead of passengers, you might ignore the party size option. For ride requests, you must resolve the following items:

  • Pickup location

  • Drop-off location

  • Party size

  • Ride option

  • Payment method

Handling a Ride Request

Handling a ride request involves booking the ride with your service and providing SiriKit with the status of the booking. The details of how you book rides through your service are up to you. You need to schedule the ride, find a vehicle and a driver, and arrange payment from the user. The INRequestRideIntent object contains information about what the user needs. Pass the information in that object to your service and use the results to configure the response object you return to SiriKit.

Listing 1 shows an example of how you might book a ride and provide a response. Because booking the actual ride is a custom process, the example calls several custom methods to implement key phases of that process. The first of these methods uses information from the intent object to register the request with a fictional service and retrieve an ID string identifying the request. Use that ID string to retrieve specific information from the service regarding the vehicle type, driver, and ride option. Use all of the retrieved information to build the INRideStatus object that and add the status object to the INRequestRideIntentResponse object passed back to SiriKit.

Listing 1

Booking a ride request

- (void)handleRequestRide:(INRequestRideIntent *)requestRideIntent
       completion:(void (^)(INRequestRideIntentResponse *requestRideIntentResponse))completion {
   INRideStatus* status = [[INRideStatus alloc] init];
 
   // Create the request in my app's ride booking software.
   // Get the resulting request ID to use for configuring the response.
   status.rideIdentifier =
      [self createNewRideRequestWithStartingLocation:requestRideIntent.pickupLocation
                                      endingLocation:requestRideIntent.dropOffLocation
                                           partySize:requestRideIntent.partySize
                                       paymentMethod:requestRideIntent.paymentMethod];
 
   // Configure the pickup and dropoff information.
   status.estimatedPickupDate = [self estimatedPickupDateForRideRequest:status.rideIdentifier];
   status.pickupLocation = requestRideIntent.pickupLocation;
   status.dropOffLocation = requestRideIntent.dropOffLocation;
 
   // Retrieve information about the assigned vehicle and driver (if any).
   status.vehicle = [self vehicleForRideRequest:status.rideIdentifier];
   status.driver = [self driverForRideRequest:status.rideIdentifier];
 
   // Configure the vehicle type and pricing.
    status.rideOption = [self rideOptionForRideRequest:status.rideIdentifier];
 
   // Commit the request and get the current status.
   status.phase = [self completeBookingForRideRequest:status.rideIdentifier];
 
   // Use the status to determine the success or failure of the request.
   INRequestRideIntentResponseCode responseCode;
   if (status.phase == INRidePhaseReceived)
      responseCode = INRequestRideIntentResponseCodeInProgress;
   else if (status.phase == INRidePhaseConfirmed)
      responseCode = INRequestRideIntentResponseCodeSuccess;
   else
      responseCode = INRequestRideIntentResponseCodeFailure;
 
   // Create the response object and fill it with the status information.
   INRequestRideIntentResponse* response = [[INRequestRideIntentResponse alloc]
                          initWithCode:responseCode userActivity:nil];
   response.rideStatus = status;
 
   // Return the response to SiriKit.
   completion(response);
}

When creating responses, providing an NSUserActivity object is optional and necessary only when you want to include custom information for your app. If you specify nil, SiriKit creates a user activity object for you as needed. For more information on configuring the response object, see INRequestRideIntentResponse.

Topics

Resolving the Intent Parameters

- resolvePickupLocationForRequestRide:withCompletion:

Resolves the pickup location for the ride.

- resolveDropOffLocationForRequestRide:withCompletion:

Resolves the drop-off location for the ride.

- resolveRideOptionNameForRequestRide:withCompletion:

Resolves the user’s selected ride option.

- resolvePartySizeForRequestRide:withCompletion:

Resolves the number of passengers for the ride.

Confirming the Response

- confirmRequestRide:completion:

Confirms that you can book the ride.

Handling the Intent

- handleRequestRide:completion:

Handles the booking of the ride.

Required.

Relationships

Inherits From

See Also

Request a Ride

INRequestRideIntent

A request to book the specified ride from your service.

INRequestRideIntentResponse

Your app’s response to a request ride intent.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software