From 167163e67e52bd2fffa34f22621b42457d1203f6 Mon Sep 17 00:00:00 2001 From: Christopher Sexton Date: Fri, 27 Mar 2020 09:19:56 -0400 Subject: [PATCH] Update documentation for v1.2 --- doc/customer.md | 4 +- doc/data_models.md | 149 +++++++++++++++++++++++++++++++++++++++++++++ doc/orders.md | 69 ++++++++++----------- doc/quickstart.md | 1 + 4 files changed, 186 insertions(+), 37 deletions(-) create mode 100644 doc/data_models.md diff --git a/doc/customer.md b/doc/customer.md index b74d1b7..91fd205 100755 --- a/doc/customer.md +++ b/doc/customer.md @@ -15,13 +15,15 @@ let customerInfo = CustomerInfo( ) // Post it to the API -FlyBuy.customer.create(withInfo: customerInfo, termsOfService: true, ageVerification: true) { (customer, error) -> (Void) in +FlyBuy.customer.create(withInfo: customerInfo, termsOfService: userAcceptedTerms, ageVerification: userVerifiedAge) { (customer, error) -> (Void) in // Handle customer or deal with error } ``` _Note: The `phone` parameter is optional_ +**IMPORTANT:** If the `termsOfService` and `ageVerification` parameters are not `true`, an error will be returned and the customer will not be created. + ## Login Via Customer Token Login the user with a previously obtained customer API token diff --git a/doc/data_models.md b/doc/data_models.md new file mode 100644 index 0000000..929994e --- /dev/null +++ b/doc/data_models.md @@ -0,0 +1,149 @@ +# FlyBuy Data Models + +Several data objects are used and returned by the FlyBuy SDK. These include: + +- [FlyBuy Data Models](#flybuy-data-models) + - [Customer Info](#customer-info) + - [Customer](#customer) + - [Site](#site) + - [Order](#order) + - [Customer State ENUM Values](#customer-state-enum-values) + - [Order State ENUM Values](#order-state-enum-values) + - [Pickup Window](#pickup-window) + - [Errors](#errors) + +## Customer Info + +The `CustomerInfo` type is used to update customer information. It is also returned in the `Order` for the customer information for an order. + +```swift +open class CustomerInfo { + public let name: String + public let carType: String? + public let carColor: String? + public let licensePlate: String? + public let phone: String? +} +``` + +## Customer + +The `Customer` type provide details of the current customer using `FlyBuy.customer.current` and is returned after creating a customer or logging in. + +```swift +open class Customer { + public let token: String + public let emailAddress: String? + public let info: CustomerInfo +} +``` + +## Site + +The `Site` type provides details for a particular site. + +```swift +open class Site { + public let id: Int + public let partnerIdentifier: String? + public let name: String? + public let phone: String? + public let fullAddress: String? + public let longitude: String? + public let latitude: String? + public let instructions: String? + public let descriptionText: String? + public let coverPhotoURL: String? +} +``` + +## Order + +The `Order` type provides details for a order. + +```swift +open class Order { + public let id: Int + public var state: OrderState + public var customerState: CustomerState + public let partnerIdentifier: String? + public let pickupWindow: PickupWindow? + public let pickupType: String? + public var etaAt: Date? + public let redeemedAt: Date? + public var customerRating: String? + public var customerComment: String? + + public let siteID: Int + public let siteName: String? + public let sitePhone: String? + public let siteFullAddress: String? + public let siteLongitude: String? + public let siteLatitude: String? + public let siteInstructions: String? + public let siteDescription: String? + public let siteCoverPhotoURL: String? + + public let customerID: String? + public let customerName: String? + public let customerCarType: String? + public let customerCarColor: String? + public let customerLicensePlate: String? +} +``` + +### Customer State ENUM Values + +`CustomerState` provides the current status of the customer. + +| Value | Description | +|-------------|-------------------------------------------------------------------------| +| `created` | Customer has claimed their order | +| `enRoute` | Order tracking has started and the customer is on their way | +| `nearby` | Customer is close to the site | +| `arrived` | Customer has arrived on site | +| `waiting` | Customer is in a pickup area or has manually indicated they are waiting | +| `completed` | Order is complete | + +### Order State ENUM Values + +`OrderState` provide the state of the order from the merchant's perspective. + +| Value | Description | +|-------------|-------------------------------------------------------------------------| +| `created` | Order has been created | +| `ready` | Order is ready for customer to claim | +| `delayed` | Order has been delayed by merchant after customer arrives | +| `cancelled` | Merchant has cancelled order | +| `completed` | Order is complete | +| `gone` | Returned by API when order does not exist | + +### Pickup Window + +The `PickupWindow` type provides the time range when an order is expected to be picked up. It will be `nil` if there is no pickup window, i.e., ASAP. If there is just a pickup time, the `start` and `end` will be the same. + +```swift +public class PickupWindow: NSObject { + public let start: Date + public let end: Date +} +``` + +## Errors + +If there is an error for any SDK method, the callback will return a swift `Error` object. + +Possible types include, but are not limited to, the following: + +```swift +public class FlyBuyError : LocalizedError { + internal(set) public var errorDescription: String? + public let title: String +} +``` + +```swift +public class FlyBuyAPIError : FlyBuyError { + public let statusCode: HTTPStatusCode? + public var errors: [String : [String]]? +``` diff --git a/doc/orders.md b/doc/orders.md index 59b91e1..1ec8506 100755 --- a/doc/orders.md +++ b/doc/orders.md @@ -1,6 +1,6 @@ # Orders -Examples are in Swift. +Examples are in Swift. Refer to [Data Models](data_models.md) for details on classes and objects used by the SDK. - [Fetch Claimed Orders](#fetch-claimed-orders) - [Fetch Unclaimed Orders](#fetch-unclaimed-orders) @@ -8,7 +8,9 @@ Examples are in Swift. - [Claim Orders](#claim-orders) - [Create Orders](#create-orders) - [Update Orders](#update-orders) -- [Rate Orders](#rate-orders) + - [Update customer state](#update-customer-state) + - [Update order state](#update-order-state) +- [Customer Ratings](#customer-ratings) ## Fetch Claimed Orders @@ -40,7 +42,7 @@ FlyBuy.orders.closed ```swift FlyBuy.orders.fetch(withRedemptionCode: code) { (order, error) - // Update order claim view with order details here + // Check error response and update order claim view with order details here } ``` @@ -74,12 +76,13 @@ func registerForNotifications() { To claim an order for the current customer, the app should call the `claim` method. ```swift +// Create the customer info struct for person picking up (name is required) let customerInfo = CustomerInfo( - name: "Bob Smith", - carType: "Honda Civic", - carColor: "white", - licensePlate: "ABC-123", - phone: "555-5555" + name: "Marty McFly", + carType: "DeLorean", + carColor: "Silver", + licensePlate: "OUTATIME", + phone: "555-555-5555" ) FlyBuy.orders.claim(withRedemptionCode: code, customerInfo: customerInfo) { (order, error) @@ -87,7 +90,15 @@ FlyBuy.orders.claim(withRedemptionCode: code, customerInfo: customerInfo) { (ord } ``` -After an order is claimed, call `FlyBuy.orders.fetch()` to update the list of orders from the server. The newly claimed order will appear in the list of open orders, which is available via `FlyBuy.orders.open`. +**IMPORTANT:** Make sure to call `FlyBuy.orders.fetch()` to sync the orders after successfully claiming the order. The newly claimed order will appear in the list of open orders, which is available via `FlyBuy.orders.open`. + +Optionally, the pickup type can be set when claiming an order. This is only necessary for apps that do not set the pickup type via backend integrations when the order is created. Supported pickup types currently include `"curbside"`, `"pickup"`, and `"delivery"`. Passing `nil` will leave the `pickupType` unchanged. + +```swift +FlyBuy.orders.claim(withRedemptionCode: code, customerInfo: customerInfo, pickupType: pickupType) { (order, error) + // If error == nil, order has been claimed +} +``` ## Create Orders @@ -101,11 +112,11 @@ Most orders will have a pickup time of "ASAP". If you have a different pickup wi ```swift let customerInfo = CustomerInfo( - name: "Bob Smith", - carType: "Honda Civic", - carColor: "white", - licensePlate: "ABC-123", - phone: "555-5555" + name: "Marty McFly", + carType: "DeLorean", + carColor: "Silver", + licensePlate: "OUTATIME", + phone: "555-555-5555" ) FlyBuy.orders.create(siteID: 101, partnerIdentifier: "1234123", customerInfo: customerInfo) { (order, error) -> (Void) in @@ -127,6 +138,8 @@ window = PickupWindow() Orders are always updated with an order event. The order object cannot be updated directly. +### Update customer state + ```swift FlyBuy.orders.event(orderID: order.id, customerState: .waiting) @@ -137,12 +150,18 @@ FlyBuy.orders.event(orderID: order.id, customerState: .waiting) { (order, error) } ``` +Refer to [Customer State ENUM Values](data_models.md#customer-state-enum-values) for possible `customerState` values. + +### Update order state + You can update an order's state, if necessary, with any valid `OrderState` enum: ```swift FlyBuy.orders.event(orderID: order.id, state: .cancelled) ``` +Refer to [Order State ENUM Values](#order-state-enum-values) for possible `state` values. + ## Customer Ratings If you collect customer ratings in your app, you can pass them to FlyBuy. The `rating` should be an integer and `comments` (optional) should be a string: @@ -151,25 +170,3 @@ If you collect customer ratings in your app, you can pass them to FlyBuy. The `r FlyBuy.orders.rateOrder(orderID: 123, rating: 5, comments: 'Great service') ``` -## Customer State ENUM Values - -| Value | Description | -|-------------|-------------------------------------------------------------------------| -| `created` | Customer has claimed their order | -| `enRoute` | Order tracking has started and the customer is on their way | -| `nearby` | Customer is close to the site | -| `arrived` | Customer has arrived on site | -| `waiting` | Customer is in a pickup area or has manually indicated they are waiting | -| `completed` | Order is complete | - - -## Order State ENUM Values - -| Value | Description | -|-------------|-------------------------------------------------------------------------| -| `created` | Order has been created | -| `ready` | Order is ready for customer to claim | -| `delayed` | Order has been delayed by merchant after customer arrives | -| `cancelled` | Merchant has cancelled order | -| `completed` | Order is complete | -| `gone` | Returned by API when order does not exist | diff --git a/doc/quickstart.md b/doc/quickstart.md index 3fa7b28..41a2576 100755 --- a/doc/quickstart.md +++ b/doc/quickstart.md @@ -110,3 +110,4 @@ Now that you have FlyBuy installed and configured, you need to integrate it with - [Managing Customers](customer.md) - [Managing Orders](orders.md) - [Managing Sites](sites.md) +- [Data Models](data_models.md)