VenueNext iOS SDK v2 Quick Start Guide

Prerequisites

For Objective-C only projects using Xcode 10.1 and higher

You must set Always Embed Swift Standard Libraries to YES in the target’s Build Settings

Integration Demo App

• venuenext/sdkDemoApp-ios

Obtaining the SDK

Manual Installation

Get the latest SDK from here:

Note: See release notes

VenueNext v3.2.0 for Swift 5.7.2+ (Xcode 14.2 and higher, including Xcode 15+)
download

VenueNext v3.2.0 for Swift 5.7 (Xcode 14.0.1)
download

VenueNext v3.2.0 for Swift 5.6.1 (Xcode 13.4.1)
download

When prompted, enter the VenueNext provided JFrog credentials.

Unzip the archive, locate the following framework:

VNWebSDK.framework

1. Drag the framework into the Frameworks group of your project in the Project Navigator.
2. When prompted for Choose options for adding these files:, ensure that the Copy items if needed option is checked.
3. Go to the General settings pane for your project
4. Under the Frameworks, Libraries, and Embedded Content section, locate the VNWebSDK.framework and ensure that the option under Embed is set to Embed & Sign

Dependencies

With Xcode 11 and 12, it is recommended to utilize the built-in Swift Package Manager to add the below dependency:

https://github.com/Kitura/Swift-JWT

VenueNext utilizes Braintree as its payment processor, which also includes Apple Pay capabilities. It is recommended that you use Swift Package Manager (SPM) to sync this dependency pointed at master:

https://github.com/braintree/braintree-ios-drop-in

Please see the Payment Processsing section of the Quick Start Guide for further instructions on how to configure payments.

Permissions

The VenueNext SDK requires usage permission descriptions to be added to your app’s info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<key>NSCameraUsageDescription</key>

• NSLocationWhenInUseUsageDescription is needed for location requests when the user is attempting to buy a Geo Exclusive marketplace experience.
• NSCameraUsageDescription is needed for Rich Checkout so a user can make QR Code scans.

Iniitialization and examples

To initialize the SDK, simply pass in your VenueNext provided organization name and instance name, which would typically happen in your AppDelegate. The SDK will default to the production environment of your hosted OrderNext platform instance.

If you are unsure of your instance name and organization name pair, please contact VenueNext support for assistance.

IMPORTANT NOTE: XCode 12 is having known issues wiith arm64 architectures in simulators due the preparation of supporting their in-house processors. When utilizing the VNWebSDK framework in Xcode 12+, it is recommended to add arm64 to your Excluded Architectures for both Debug and Release for Any iOS Simulator.

Objective-C

#import "AppDelegate.h"
@import VNWebSDK;

@interface AppDelegate ()

@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Use this method signature to initialize for production environment
    // Deprecated in v2.0.9
    // [[VenueNextWeb shared] initialize: @"organization"];
    // Introduced in v2.0.9
    [[VenueNextWeb shared] initialize: @"organization" instance: @"instance"];

    // Use this method signature to initialize for an environment other than production
    // Deprecated in v2.0.9
    // [[VenueNextWeb shared] initialize: @"organization" env: @"dev" ];
    // Introduced in v2.0.9
    [[VenueNextWeb shared] initialize: @"organization" instance: @"instance" env: @"dev" ];

    return YES;
}

Swift

import UIKit
import VNWebSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Use this method signature to initialize for production environment
        // Deprecated in v2.0.9
        // VenueNextWeb.shared.initialize("<YOUR-ORDERNEXT_INSTANCE>")
        // Introduced in v2.0.9
        // This would point to yourordernextinstance.ordernext.com
        VenueNextWeb.shared.initialize("<ORGANIZATION_NAME>", instance: "<YOUR_ORDERNEXT_INSTANCE>")

        // Use this method signature to initialize for an environment other than production
        // Deprecated in v2.0.9
        // VenueNextWeb.shared.initialize("<YOUR-ORDERNEXT_INSTANCE>")
        // Introduced in v2.0.9
        // This would point to yourordernextinstance-env.ordernext.com
        VenueNextWeb.shared.initialize("<ORGANIZATION_NAME>", instance: "<YOUR_ORDERNEXT_INSTANCE>", env: "<ENV>")
        return true
    }
}

Note: For testing purposes, you will be provided with a pem file that is configured for example.ordernext.com. Therefore, when testing with this pem file, you should initialize using VenueNextWeb.shared.initialize("example").

If you see a white screen with a red “Please enter a valid code” message, it is likely you are trying to use an invalid pem file and OrderNext instance combination.

Setting an External User

NOTE:If you are using a third party provider for login, such as Ticketmaster, please see also External login providers.

The VenueNext SDK also supports linking of external users provided from various authentication providers such as TicketMaster.

Caching and consistently passing the correct User information to the VenueNext SDK is the responsibility of the integrator, and can simply be done by calling the below method:

VenueNextWeb.shared.setUser(
    User("1111")
)

If you wish to pass additional data to associate with the externally provided user ID upon first association, the following additional parameters are supported:

User(
    "<USER_UUID>",
    email:"<USER_EMAIL>",
    firstName:"<USER_FIRST_NAME>",
    lastName:"<USER_LAST_NAME>",
    phoneNumber:"<USER_PHONE_NUMBER>",
    accessToken:"<PSDK_ACCESS_TOKEN>"
)

NOTE: If you are utilizing the Ticketmaster Presence SDK, please ensure to include _only_ the accessToken and "ticketmaster" as the provider for the User(...) in the VenueNextWeb.shared.setUser(...) call in order for automatic authorization to work.

Convenience initialization methods are provided in the User model object to pass in any combination of the above properties.

Upon first passing of a unique external user, a VenueNext account will be created and associated with that ID. Any subsequent passing of the same user ID will automatically login the user upon display of any of the OrderNext screens provided.

Should the need arise to switch users, simply pass in the new User object and information and the previously logged in user will automatically be logged out, and the OrderNext web platform will switch to or create the new user for you.

Logging an External User Out

To log the user out of your Ordering Web instance on next presentation of an Ordering Web view:

VenueNextWeb.shared.logUserOut()

External login providers

In the event that you are using a partnered login provider (e.g. Ticketmaster) and are not just passing in an ID and associated user information that you have created yourself, the provider parameter of the User object when passed in also will need to be set.

These lowercased, case sensitive strings will be provided to you as an integrator on a case-by-case basis, and if you are unsure if you require one, please contact VenueNext support.

Also note that the VNWebSDK does not persist user logins across app sessions. If your ticketing provider does persist logins across multiple app session, you will need to set VN User for every new app launch before navigating to VenueNext views. Otherwise, the VNWebSDK will use an anonymous user until the user logs in via the VNWebSDK UI, or until an external user is set.

Supported Login Providers

Currently supported providers are:

• ticketmaster
• axs
• seatgeek

In the event that you attempt to pass in an unsupported provider, the web view will fail to load and log out an error.

Ticketmaster Login Provider

If you are utilizing Ticketmaster as your login provider, only the accessToken and "ticketmaster" as the provider need to be set for the User(...) in the VenueNextWeb.shared.setUser(...) call.

VenueNextWeb.shared.setUser(
  User(
    accessToken: accessToken,
    provider: "ticketmaster"
  )
)

Only .accountManager access tokens should be used to set the VenueNext User. .host access tokens will not authenticate.

This should be done in the onLoginSuccessful and onTokenRefreshed methods of your PresenceLoginDelegate.

public func onLoginSuccessful(backendName: PSDK.BackendName, accessToken: String) {
  if (backendName == .accountManager) {
    VenueNextWeb.shared.setUser(
    User(accessToken: accessToken, provider: "ticketmaster")
    )
  }
}

public func onTokenRefreshed(backendName: PSDK.BackendName, accessToken: String) {
  if (backendName == .accountManager) {
    VenueNextWeb.shared.setUser(
    User(accessToken: accessToken, provider: "ticketmaster")
    )
  }
}

Since the VNWebSDK does not persist logins across multiple app sessions, you should also check if a user is signed into the Presence SDK for new app launches prior to presenting any VNWebSDK views. If the user is signed in, be sure to also set the VenueNext User before showing any VNWebSDK views.

guard presence.hasUserSignedInTeam()
else { return }

getAccessToken(backendName: .accountManager) { accessToken in
  guard VenueNextWeb.shared.currentUser == nil else { return }

  VenueNextWeb.shared.setUser(
    User(accessToken: accessToken, provider: "ticketmaster")
  )
}
failure: { (error, bool) in
  // TODO: Handle failure
}

SeatGeek Login Provider

If you are utilizing SeatGeek as your login provider, only the id and the provider need to be set for the User(...) in the VenueNextWeb.shared.setUser(...) call. The user’s CRM ID should be passed as the id, and "seatgeek" should be passed as the `provider.

VenueNextWeb.shared.setUser(
  User(
    id: crmId,
    provider: "seatgeek"
  )
)

JWT and Private Key PEM

When utilizing the User object to pass in information for an external user, VenueNext secures this information via a JSON Web Token (JWT) to verify that the communication is coming from who you say you are and that the information has not been tampered with or intercepted.

A Privacy Enhanced Mail (PEM) file should have been provided to you by VenueNext. If not, please contact VenueNext support in order to obtain this file if you plan on using external user sign in and linkage. If you do not have the need to provide external user credentials, this step is not required.

The SDK provides a few options in how you can provide the private key (use only one of the following methods):

1. Drag-and-drop the *.pem file into the root folder of your project.
2. When prompted by the Choose options for adding these files: window, ensure that Copy items if needed is checked and that your app’s target is checked in the Add to targets: view.
3. Click on your project in the Project Navigator, and then go to the Build Phases tab and ensure the *.pem file has been added to the Copy Bundle Resources. If not, please add it there.

Then in your initialization code, provide the *.pem via the following method:

VenueNextWeb.shared.privateKeyPath = URL(fileURLWithPath: Bundle.main.path(forResource: "<FILE_NAME>", ofType: "pem")!)

Provide the key via a string literal

VenueNextWeb.shared.privateKeyString = """
-----BEGIN PRIVATE KEY-----
...
...
...
-----END PRIVATE KEY-----
"""

NOTE: Please ensure to leave the key header and footer in the string literal as that will be parsed out by the SDK.

Provide a signed JWT instead

The SDK also gives you the option to provide a signed JWT via:

VenueNextWeb.shared.signedJWT = "signed.jwt.here"

The VN User object is serializable, so you can easily retrieve your claims to sign as such:

let user = User(
    "1111",
    email: "demo@demo.com",
    firstName: "Joe",
    lastName: "Doe",
    phoneNumber: nil,
    provider: "ticketmaster"
)

let data = try? JSONEncoder().encode(user)
let serializedString = String(data: data!, encoding: .utf8)!

print(serializedString)
// {"id":"1111","email":"demo@demo.com","first_name":"John","last_name":"Doe","provider":"ticketmaster"}

Please ensure to use the following headers as well for conformity’s sake:

{
  "alg": "ES256",
  "typ": "JWT"
}

Prefill Section/Row/Seat

If wish to support the ability to prefill a user’s Section/Row/Seat for delivery orders, this is possible by calling the following method before presenting any VenueNext screens:

VenueNextWeb.shared.setSectonRowSeat(sectionRowSeat: SectionRowSeat?)

Please note that if the string based data for any of the Section/Row/Seat fields do not match with what VenueNext has set for a particular venue, this operation will silently fail for the field in question that has erroneous data.

Payment Processing

Note: If you are using Shift4 to process payments, no configurations or information is needed. The details below are only for Braintree.

The VNBraintree.swift file will enable the bulk of the payment processing functionality and should be used exactly as provided.

If you are not utilizing Apple Pay and will only be allowing Credit Card support through Braintree, then initializing the payment processor is as simple as:

VenueNextWeb.shared.configureBrainTree(VNBraintree())

and you’re set to accept payments! All processing and UI presentation happens automatically through the SDK.

This method should be called right after your VenueNextWeb.shared.initialize(...) call, and will need to have been called before presenting any VenueNext views or an error in the console will be printed.

If you are utilizing Apple Pay, please see the Apple Pay page for further instructions on how to configure your application.

Deep Links

To support app scheme based deep linking directly to VenueNext screens, please direct yourself to the deep linking capability section.

Deployment

When deploying an app using the VNWebSDK via Xcode’s App Store Connect distribution option, please ensure the Manage Version and Build Number option is disabled.