Table of Contents

  1. Start Booking
  2. Deep linking data
  3. Further reading

1. Start Booking

Start the booking flow by doing:

Mozio.shared.startBooking(presenter: self)
[[Mozio shared] startBookingWithPresenter:self];


We will use the user’s GPS position as the start location, the user will be prompted to enter the destination as seen next:

2. Deep linking data

2.1 Deep linking passenger data

In the booking flow, the user will be required to enter the passenger information. If you already know this data you can deep link it to us and we’ll pre-fill those fields:

let passengerData = MozioPassengerData(firstName: "John",
                                       lastName: "Doe",
                                       email: "jd@example.com",
                                       phoneCountryCode: "US",
                                       phoneNumber: "786123456")

let bookingData = MozioBookingData()
bookingData.passengerData = passengerData

Mozio.shared.startBooking(presenter: presenter, bookingData: bookingData)
MozioPassengerData* passengerData = [[MozioPassengerData alloc] initWithFirstName:@"John"
                                                                         lastName:@"Doe"
                                                                            email:@"jd@example.com"
                                                                 phoneCountryCode:@"US"
                                                                      phoneNumber:@"786123456"];
MozioBookingData *bookingData = [[MozioBookingData alloc] init];
bookingData.passengerData = passengerData;

[[Mozio shared] startBookingWithPresenter:self bookingData:bookingData];


Now the confirmation screen will be prefilled:

2.2 Deep linking locations search data

In the booking flow, user will be required to enter the start and end locations of the ride. If you already know this data you can deep link it to us and we’ll pre-fill those fields.

For example, let’s say that the user just purchased a flight ticket that departs from San Francisco Airport and you want to offer to book a ride there. This is how you’d deep link that search:

// The start location will be the user's GPS location
let start = MozioSearchLocation.gps()

// The end location is the San Francisco Airport
let end = MozioSearchLocation.place(latitude: 37.6213129, // required
                                    longitude: -122.3811441, // required
                                    googleId: "ChIJVVVVVYx3j4ARyN7qnq2JceQ", // optional
                                    address: "San Francisco Airport" // optional
                                    )

let searchData = MozioSearchData(startLocation: start, endLocation: end)

let bookingData = MozioBookingData()
bookingData.searchData = searchData

Mozio.shared.startBooking(presenter: presenter, bookingData: bookingData)
// The start location will be the user's GPS location
MozioSearchLocation* start = [MozioSearchLocation gps];

// The end location is the San Francisco Airport
MozioSearchLocation* end = [MozioSearchLocation placeWithLatitude:37.6213129 // required
                                                        longitude:-122.3811441 // required
                                                         googleId:@"ChIJVVVVVYx3j4ARyN7qnq2JceQ" // optional
                                                          address:@"San Francisco Airport"]; // optional


MozioSearchPickupTime* pickupTime = [MozioSearchPickupTime leaveNow];
MozioSearchData* searchData = [[MozioSearchData alloc] initWithStartLocation:start endLocation:end pickupTime:pickupTime];

MozioBookingData *bookingData = [[MozioBookingData alloc] init];
bookingData.searchData = searchData;

[[Mozio shared] startBookingWithPresenter:self bookingData:bookingData];


User will be taken directly to search results as seen next:

You will notice that the googleId and address fields are optional and you can pass nil to them. We recommend providing this data if you already have it to get more accurate results.

The googleId field corresponds to Google’s unique identifier for places (PlaceID), you can read more about it here.

2.3 Deep linking pickup time search data

In the booking flow, user can either search for rides at the current time or in advance for a date in the future. This information is editable through the app, but if you already know the date for which the user will be interested in booking a ride, you can deep link it to us. To do so, you need to specify a pickupTime on the MozioSearchData.

let searchData = MozioSearchData(startLocation: nil, endLocation: nil, pickupTime: .leaveNow())
MozioSearchPickupTime* pickupTime = [MozioSearchPickupTime leaveNow];
MozioSearchData* searchData = [[MozioSearchData alloc] initWithStartLocation:nil endLocation:nil pickupTime:pickupTime];


There are three ways of building a MozioSearchPickupTime:

  • Using the leaveNow() method, which will configure the search for the moment of the booking. This is the default behavior if no pickupTime is set.
  • Using the specificDate(date: Date) method, which will configure the search for the given date.
  • Using the roundTrip(outboundDate: Date, returnDate: Date) method, which will configure the search for a round trip considering the two dates. Note that the outboundDate must precede the returnDate. If given dates do not represent a valid time segment in the future, return value will be MozioSearchPickupTime.leaveNow(), the user will then have to manually enter outbound and return dates.

The specific Date doesn’t consider time zones, and Mozio will return results for the time sent at the time zone of the location used. Every app handles dateTimes on a different way, so let’s go through a couple of examples detailing how to build the Date object depending on your situation.

From time interval
If you want the search to throw results, for example, in a week:

let date = Date().addingTimeInterval(7*24*60*60) // In 1 week
let pickupTime = MozioSearchPickupTime.specificDate(date: date)
NSDate* date = [[NSDate alloc] initWithTimeIntervalSinceNow:7*24*60*60]; // In 1 week
MozioSearchPickupTime* pickupTime = [MozioSearchPickupTime specificDateWithDate:date];


From timestamp without timezone
If your app deals with String timestamps that don’t include a timezone, you can just use a DateFormatter to extract the Date object from it.

let timestamp = "2019-09-28T17:30"
let dateFormatter = DateFormatter()
dateFormatter.dateFormat = "yyyy-MM-dd'T'HH:mm"
let date = dateFormatter.date(from: timestamp)! // Will create a Date corresponding to September 28th, 17:30
let pickupTime = MozioSearchPickupTime.specificDate(date: date)
NSString* timestamp = @"2019-09-28T17:30";
NSDateFormatter* dateFormatter = [[NSDateFormatter alloc] init];
dateFormatter.dateFormat = @"yyyy-MM-dd'T'HH:mm";
NSDate* date = [dateFormatter dateFromString:timestamp];// Will create a Date corresponding to September 28th, 17:30
MozioSearchPickupTime* pickupTime = [MozioSearchPickupTime specificDateWithDate:date];


From timestamp with timezone
If your app deals with String timestamps that include a timezone, the easiest way is removing the timezone indication from the String before parsing it as a Date.

extension String {
    func removingTimeZone() -> String {
        if hasSuffix("GMT") {
            // Example: "2019-08-29T17:32:00GMT"
            return replacingOccurrences(of: "GMT", with: "")
        } else if hasSuffix("Z") {
            // Example: "2019-08-29T17:32:00Z"
            return replacingOccurrences(of: "Z", with: "")
        } else {
            // Examples: "2019-08-29T17:32:00+0700", "2019-08-29T17:32:00-0200"
            let index = count - 5
            return String(prefix(index))
        }
    }
}

let timestamp = "2019-09-28T17:30:00+0700"
let dateFormatter = DateFormatter()
dateFormatter.dateFormat = "yyyy-MM-dd'T'HH:mm:ss"
let date = dateFormatter.date(from: timestamp.removingTimeZone())! // Will create a Date corresponding to September 28th, 17:30
let pickupTime = MozioSearchPickupTime.specificDate(date: date)
@implementation NSString (TimeZoneRemoval)

- (NSString *)removingTimeZone {
    if ([self hasSuffix:@"GMT"]) {
        // Example: "2019-08-29T17:32:00GMT"
        return [self stringByReplacingOccurrencesOfString:@"GMT" withString:@""];
    } else if ([self hasSuffix:@"Z"]) {
        // Example: "2019-08-29T17:32:00Z"
        return [self stringByReplacingOccurrencesOfString:@"Z" withString:@""];
    } else {
        // Examples: "2019-08-29T17:32:00+0700", "2019-08-29T17:32:00-0200"
        NSUInteger index = self.length - 5;
        return [self substringToIndex:index];
    }
}

@end

NSString* timestamp = @"2019-09-28T17:30:00+0700";
NSDateFormatter* dateFormatter = [[NSDateFormatter alloc] init];
dateFormatter.dateFormat = @"yyyy-MM-dd'T'HH:mm:ss";
NSString *timestamptWithoutTimeZone = [timestamp removingTimeZone];
NSDate* date = [dateFormatter dateFromString:timestamptWithoutTimeZone];// Will create a Date corresponding to September 28th, 17:30
MozioSearchPickupTime* pickupTime = [MozioSearchPickupTime specificDateWithDate:date];


Note that the corresponding removingTimeZone method should be adapted depending on the format used by your app.

2.4 Deep linking currency

You can specify the currency to be used for all prices by using the ISO 4217 currency code.

For example, if you’d like all prices to be displayed in MXN (Mexican Peso):

let bookingData = MozioBookingData()
bookingData.currency = "MXN"

Mozio.shared.startBooking(presenter: presenter, bookingData: bookingData)
MozioBookingData *bookingData = [[MozioBookingData alloc] init];
bookingData.currency = @"MXN";

[[Mozio shared] startBookingWithPresenter:self bookingData:bookingData];


When you don’t specify a currency, all prices are displayed in USD.

2.5 Deep linking booking features

You can specify which features should the user have available on the SDK when booking a ride. Such specifications can be done on the MozioBookingFeatures object, which has the following attributes (all enabled by default).

  • futureBookingEnabled: defines if user will be able to book rides on a specific future date.
  • leaveNowEnabled: defines if user will be able to book rides for the time of the search (Leave now).
  • storingCardsEnabled: defines if user will be able to store his credit/debit card information on Mozio’s session.
let bookingData = MozioBookingData()
bookingData.features.futureBookingEnabled = false

Mozio.shared.startBooking(presenter: presenter, bookingData: bookingData)
MozioBookingData *bookingData = [[MozioBookingData alloc] init];
bookingData.features.futureBookingEnabled = false;

[[Mozio shared] startBookingWithPresenter:self bookingData:bookingData];


Notes:

  • Mozio strongly recommends leaving every feature enabled. These should only be disabled in case there is an explicit requirement to disable one of them.
  • At least one of futureBookingEnabled or leaveNowEnabled must be enabled. If your app invokes the booking flow with both features disabled, the call will be ignored and no screen will be presented to the user.
  • Mozio will never store card information without user’s consent. The fact that storingCardsEnabled is set to true doesn’t mean that Mozio will keep the card data by default: user will still need to approve such behavior when entering the card details.

2.6 Deep linking payment data

Your app will probably keep payment information about the users (credit and debit cards). If desired, this information can be deep linked to Mozio so that users can use the same cards for the booking of rides. The explanation of such feature can be found at our Deep linking payment data guide.

2.7 Deep linking extra data

You can specify extra data to be linked with the reservation as follows:

let data = MozioBookingExtraData(campaign: "ios-sdk",
                                 branch: "confirmation_email",
                                 partnerTrackingId: "f486b746-7da0-11e9-8f9e-2a86e4085a59")

let bookingData = MozioBookingData()
bookingData.extraData = data

Mozio.shared.startBooking(presenter: presenter, bookingData: bookingData)
MozioBookingExtraData* extraData = [[MozioBookingExtraData alloc] initWithCampaign:@"ios_sdk"
                                                                            branch:@"confirmation_email"
                                                                 partnerTrackingId:@"f486b746-7da0-11e9-8f9e-2a86e4085a59"];

MozioBookingData *bookingData = [[MozioBookingData alloc] init];
bookingData.extraData = extraData;

[[Mozio shared] startBookingWithPresenter:self bookingData:bookingData];


Passed data through this method will be available in the reports sent each month via email.

3. Further reading

There are other topics you will need to cover, like adding Tracking status to your UI and using the Staging environment to test the booking flow.
Full details in our Advanced guide.