VenueNext Android SDK v2 Quick Start Guide

System Requirements

• Minimum SDK Version 21 - Android 5.0 “Lollipop”

Integration Demo App

• venuenext/sdkDemoApp-android

Obtaining the SDK

Manual Installation

The VenueNext Android SDK is served via JFrog. Follow the guide below using your provided credentials to obtain the SDK.

Add the following dependencies to your project’s build.gradle file:

buildscript {
    ext {
        kotlin_version = '1.9.10'
        serialization_version = '1.0.1'
        dokka_version = "0.10.1"
    }
    repositories {
        mavenCentral()
        google()
        jcenter()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:4.0.0"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
        classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version"
        classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokka_version"
    }
}

allprojects {
    repositories {
        mavenCentral()
        google()
        jcenter()
    }
}

Add the following plugin and repository to your app’s build.gradle file:

plugins {
  ...
  id 'org.jetbrains.kotlin.android'
  id 'maven-publish'
  id 'kotlinx-serialization'
}

...

android {...}

repositories {
  maven {
    url "https://venuenext.jfrog.io/venuenext/android-sdk"
    credentials {
      username = XXXXXXXXXXXXXXXXX
      password = XXXXXXXXXXXXXXXXX
    }
  }
}

dependencies {...}

Important: Please keep the Maven username and password secure and do not share it with anyone.

Add the following VenueNext dependency to your app’s build.gradle file:

dependencies {
  ...
  //////// VN Web SDK Dependencies ////////
  // VN Web SDK
  implementation 'com.venuenext:vnwebsdk:2.4.0'

  // Kotlin
  implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
  implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:$serialization_version")
  implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:$serialization_version")

  // Android
  implementation 'androidx.core:core-ktx:1.12.0'
  implementation 'androidx.appcompat:appcompat:1.6.1'
  implementation 'androidx.constraintlayout:constraintlayout:2.1.4'

  // JWT
  api 'io.jsonwebtoken:jjwt-api:0.11.5'
  runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.11.5'
  runtimeOnly('io.jsonwebtoken:jjwt-orgjson:0.11.5') {
    exclude group: 'org.json', module: 'json' //provided by Android natively
  }
  /////////////////////////////////////////
  ...
}

Manifest permissions

In order to utilize all the basic functionality of the VenueNext SDK, add the following permissions to your AndroidManifest.xml.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="<PACKAGE_NAME>">

    ...

    <!-- Needed to access all basic functionality of the SDK -->
    <uses-permission android:name="android.permission.INTERNET" />
    <!-- Needed for QR Code scanning via Rich Checkout -->
    <uses-permission android:name="android.permission.CAMERA" />
    <!-- Needed to adjust the screen brightness when viewing a QR Code -->
    <uses-permission android:name="android.permission.WRITE_SETTINGS"
    tools:ignore="ProtectedPermissions"/>
    <!-- Needed to determine user's location when attempting to purchase a Geo Exclusive marketplace experience -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    ...

    <application..>

</manifest>

Initialization

To initialize the SDK, simply pass in your VenueNext provided organization name and instance name, which would typically happen in your MainActivity. 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.

class MainActivity : AppCompatActivity() {
    ...

    override fun onCreate(savedInstanceState: Bundle?) {
        ...

        /*
        Use this method signature to initialize VN. This will default to a production environment.
        This would point to <INSTANCE_NAME>.ordernext.com
        */
        // VenueNextWeb.initialize("<YOUR-ORGANIZATION_NAME>", "<INSTANCE_NAME>"")
        /*
        Use this method signature to initialize for an environment other than production.
        This would point to <INSTANCE_NAME>-<ENVIRONMENT>.ordernext.com.
        */
        // VenueNextWeb.initialize("<ORGANIZATION_NAME>", "<INSTANCE_NAME>", "<ENVIRONMENT>")
    }

    ...
}

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.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.setUser(
    User(id = "xxxx-xxxx-xxxx")
)

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(
    id="<USER_UUID>",
    email="<USER_EMAIL>",
    firstName="<USER_FIRST_NAME>",
    lastName="<USER_LAST_NAME>",
    phoneNumber="<USER_PHONE_NUMBER>",
    accessToken="<PSDK_ACCESS_TOKEN>"
)

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.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.

Supported Login Providers

Currently supported providers are:

• ticketmaster
• axs
• seatgeek

NOTE: If you are utilizing the Ticketmaster Presence SDK, please ensure to include only the accessToken and "ticketmaster" as the provider in the User(...) in the VenueNextWeb.setUser(...) call.

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.setUser(...) call.

VenueNextWeb.setUser(
    User(
        accessToken = accessToken,
        provider = "ticketmaster"
    )
)

Only ARCHTICS 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 PresenceSdkConfigListener.

    override fun onLoginSuccessful(p0: BackendName?, p1: String?) {
        if (p1.isNullOrEmpty()) return

        if (p0 == ARCHTICS) {
            VenueNextWeb.setUser(
                User(
                    accessToken = p1,
                    provider = "ticketmaster"
                )
            )
        }
    }

    override fun onTokenRefreshed(p0: BackendName?, p1: String?) {
        if (p1.isNullOrEmpty()) return

        if (p0 == ARCHTICS) {
            VenueNextWeb.setUser(
                User(
                    accessToken = p1,
                    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.

if (!PresenceSDK.getPresenceSDK(context).hasUserSignedIntoTeam()) return

getMemberInfo(ARCHTICS) { member, error ->
   if (member != null) {
       PresenceSDK.getAccessToken(context, backendName, <YOUR_TM_LOGIN_LISTENTER>)
   }
}

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.setUser(...) call. The user’s CRM ID should be passed as the id, and "seatgeek" should be passed as the `provider.

VenueNextWeb.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):

Provide via the key to the SDK via the *.pem file

Android Studio Project Explorer View

1. Expand your folder directory to your source directory. Traditionally, this would be app -> src -> main
2. Right click, and press New -> Folder -> Assets Folder
3. Place the *.pem file in this directory.

Android Studio Android Explorer View

1. Right click on your project module, which is traditionally app.
2. New -> Folder -> Assets Folder
3. Place the *.pem file in this directory.

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

VenueNextWeb.privateKeyAssetName = "<YOUR_FILE_NAME_HERE>.pem"

Provide the key via a string literal

VenueNextWeb.privateKeyString = """
    -----BEGIN PRIVATE KEY-----
    ...
    ...
    ...
    -----END PRIVATE KEY-----
""".trimIndent()

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.signedJWT = "signed.jwt.here"

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

val user = User(
    id="1111",
    email="demo@demo.com",
    firstName="John",
    lastName="Doe",
    phoneNumber=null,
    provider="ticketmaster"
)
val json = Json.encodeToString(user)

// json claims: {"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.

Deep Links

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