VenueNext Android SDK Quick Start Guide

System Requirements

• Minimum SDK Version 24 - Android 7.0 “Nougat”

Integration Demo App

• venuenext/sdkDemoApp-android

Obtaining the SDK

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 {
        build_tools_version = '8.10.1'
        kotlin_version = '2.2.0'
        serialization_version = '1.6.0'
        dokka_version = "0.10.1"
    }
    repositories {
        mavenCentral()
        google()
        jcenter()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:$build_tools_version"
        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.6.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.17.0'
  implementation 'androidx.appcompat:appcompat:1.7.1'
  implementation 'androidx.constraintlayout:constraintlayout:2.2.1'

  // JWT
  api 'io.jsonwebtoken:jjwt-api:0.13.0'
  runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.13.0'
  runtimeOnly('io.jsonwebtoken:jjwt-orgjson:0.13.0') {
    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 may be provided with a pem file configured for example.ordernext.com. When using this file, initialize with the matching organization/instance pair, for example VenueNextWeb.initialize("example", "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 for ticketing, please ensure to include the email and id in the User(...) in the VenueNextWeb.setUser(...) call. The provider should be "ticketmaster".

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 the Ticketmaster Presence SDK for ticketing, please ensure to include the email and id in the User(...) in the VenueNextWeb.setUser(...) call. The provider should be "ticketmaster".

VenueNextWeb.setUser(
    User(
        id = "<TM_USER_ID>",
        email = "<EMAIL>",
        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.

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

To enable external user sign-in in VenueNext web experiences, call VenueNextWeb.setUser(...) and configure one signing option below.

A Privacy Enhanced Mail (PEM) file should have been provided to you by VenueNext. If not, please contact VenueNext support to obtain one for external user sign-in/linkage. If you do not pass external users to the SDK, this step is not required.

Signing source precedence (important)

When a User is present, the SDK resolves signing configuration in this order:

1. VenueNextWeb.privateKeyAssetName
2. VenueNextWeb.privateKeyString
3. VenueNextWeb.signedJWT

If none are configured (or if no User is set), external user authentication is not applied.

Option 1: Provide a PEM and let the SDK sign JWTs (app-side signing)

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"

Option 1b: Provide the PEM contents as 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.

Option 2: Provide a signed JWT directly

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

VenueNextWeb.signedJWT = "signed.jwt.here"

If you sign externally, the JWT claims should mirror the User payload sent to the SDK. The VN User object is serializable, so you can retrieve claims like this:

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"}

Use the following JWT header:

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

Best practices for PEM files and signed JWTs

• Server-side signing (signedJWT) is generally considered the most secure approach when feasible, since private keys remain on your backend.
  • PEM/private keys are most secure when kept server-side; if you do ship a PEM/private key in your app, keep it out of source control and rotate it regularly.
• Configure only one of privateKeyAssetName, privateKeyString, or signedJWT at a time to avoid precedence confusion.
• Always set the external User before presenting VenueNext screens; external user authentication is skipped when User is null.
• Regenerate/sign a new JWT whenever the user changes, then call VenueNextWeb.setUser(...) with that user.
• Keep provider values lowercase and exact (for example ticketmaster, axs, seatgeek).
• Never log full PEM material or full JWT strings in production logs.

Prefill Section/Row/Seat

If you wish to support prefilling a user’s Section/Row/Seat for delivery orders, call the following method before presenting VenueNext screens:

VenueNextWeb.setSectionRowSeat(
    SectionRowSeat(section = "A", row = "12", seat = "3")
)

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.