xenon-view-sdk

The Xenon View Swift SDK is the Swift SDK to interact with XenonView.

Table of contents:

• What's New
• Introduction
• Steps To Get Started
  • Identify Business Outcomes
  • Identify Customer Journey Milestones
  • Enumerate Technical Stack
  • Installation
  • Instrument Business Outcomes
  • Instrument Customer Journey Milestones
  • Determine Commit Points
  • (Optional) Group Customer Journeys
  • Analysis
  • Perform Experiments
• Detailed Usage
  • Installation
  • Initialization
  • Service/Subscription/SaaS Business Outcomes
  • Ecommerce Business Outcomes
  • Customer Journey Milestones
    • Features Usage
    • Content Interaction
  • Commit Points
  • Heartbeats
  • Platforming
  • Experiments
  • Customer Journey Grouping
  • Other Considerations
    • (Optional) Error Handling
    • (Optional) Custom Customer Journey Milestones
    • (Optional) Journey Identification
• License

What's New

• v0.1.2 - Added: Downsell, Ad, Content Archive, Subscription Pause and included price/term for all subscriptions.
• v0.1.1 - Rename tag to variant
• v0.1.0 - SDK redesign

Introduction

Everyone should have access to world-class customer telemetry.

You should be able to identify the most pressing problems affecting your business quickly. You should be able to determine if messaging or pricing, or technical challenges are causing friction for your customers. You should be able to answer questions like:

1. Is my paywall wording or the price of my subscriptions causing my customers to subscribe less?
2. Is my website performance or my application performance driving retention?
3. Is purchasing a specific product or the product portfolio driving referrals?

With the correct approach to instrumentation coupled with AI-enhanced analytics, you can quickly answer these questions and much more.

back to top

Get Started With The Following Steps:

The Xenon View SDK can be used in your application to provide a new level of customer telemetry. You'll need to embed the instrumentation into your website/application via this SDK.

Instrumentation will vary based on your use case; are you offering a service/subscription (SaaS) or selling products (Ecom)?

In a nutshell, the steps to get started are as follows:

1. Identify Business Outcomes and Customer Journey Milestones leading to those Outcomes.
2. Instrument the Outcomes/Milestones.
3. Analyze the results.

Step 1 - Business Outcomes

Regardless of your business model, your first step will be identifying your desired business outcomes.

Example - Service/Subscription/SaaS:

1. Lead Capture
2. Account Signup
3. Initial Subscription
4. Renewed Subscription
5. Upsold Subscription
6. Referral

Example - Ecom:

1. Place the product in the cart
2. Checkout
3. Upsold
4. Purchase

:memo: Note: Each outcome has an associated success and failure.

Step 2 - Customer Journey Milestones

For each Business Outcome, identify potential customer journey milestones leading up to that business outcome.

Example - Service/Subscription/SaaS for Lead Capture:

1. View informational content
2. Asks question in the forum
3. Views FAQs
4. Views HowTo
5. Requests info product

Example - Ecom for Place product in cart :

1. Search for product information
2. Learns about product
3. Read reviews

Step 3 - Enumerate Technical Stack

Next, you will want to figure out which SDK to use. We have some of the most popular languages covered.

Start by listing the technologies involved and what languages your company uses. For example:

1. Front end - UI (Javascript - react)
2. Back end - API server (Java)
3. Mobile app - iPhone (Swift)
4. Mobile app - Android (Android Java)

Next, figure out how your outcomes spread across those technologies. Below are pointers to our currently supported languages:

• React
• Next.Js
• Angular
• HTML
• Plain JavaScript
• iPhone/iPad
• Mac
• Java
• Android Java
• Python

Finally, continue the steps below for each technology and outcome.

Step 4 - Installation

After you have done the prework of Step 1 and Step 2, you are ready to install Xenon View. Once installed, you'll need to initialize the SDK and get started instrumenting.

Step 5 - Instrument Business Outcomes

We have provided several SDK calls to shortcut your instrumentation and map to the outcomes identified in Step 1.
These calls will roll up into the associated Categories during analysis. These rollups allow you to view each Category in totality. As you view the categories, you can quickly identify issues (for example, if there are more Failures than Successes for a Category).

Service/Subscription/SaaS Related Outcome Calls (click on a call to see usage)

Category	Success	Decline
Lead Capture	leadCaptured()	leadCaptureDeclined()
Account Signup	accountSignup()	accountSignupDeclined()
Application Installation	applicationInstalled()	applicationNotInstalled()
Initial Subscription	initialSubscription()	subscriptionDeclined()
Subscription Renewed	subscriptionRenewed()	subscriptionCanceled() / subscriptionPaused()
Subscription Upsell	subscriptionUpsold()	subscriptionUpsellDeclined() / subscriptionDownsell()
Ad Clicked	adClicked()	adIgnored()
Referral	referral()	referralDeclined()

Ecom Related Outcome Calls (click on a call to see usage)

Category	Success	Decline
Lead Capture	leadCaptured()	leadCaptureDeclined()
Account Signup	accountSignup()	accountSignupDeclined()
Add To Cart	productAddedToCart()	productNotAddedToCart()
Product Upsell	upsold()	upsellDismissed()
Checkout	checkedOut()	checkoutCanceled() / productRemoved()
Purchase	purchased()	purchaseCanceled()
Promise Fulfillment	promiseFulfilled()	promiseUnfulfilled()
Product Disposition	productKept()	productReturned()
Referral	referral()	referralDeclined()

Step 6 - Instrument Customer Journey Milestones

Next, you will want to instrument your website/application/backend/service for the identified Customer Journey Milestones Step 2. We have provided several SDK calls to shortcut your instrumentation here as well.

During analysis, each Milestone is chained together with the proceeding and following Milestones. That chain terminates with an Outcome (described in Step 4). AI/ML is employed to determine Outcome correlation and predictability for the chains and individual Milestones. During the analysis step, you can view the correlation and predictability as well as the Milestone chains (called Customer Journeys in this guide).

Milestones break down into two types (click on a call to see usage):

Features	Content
featureAttempted()	contentViewed()
featureFailed()	contentCreated() / contentEdited()
featureCompleted()	contentDeleted() / contentArchived()
	contentRequested()/contentSearched()

Step 7 - Commit Points

Once instrumented, you'll want to select appropriate commit points. Committing will initiate the analysis on your behalf by Xenon View.

Step 8 (Optional) - Group Customer Journeys

All the customer journeys (milestones and outcomes) are anonymous by default. For example, if a Customer interacts with your brand in the following way:

1. Starts on your marketing website.
2. Downloads and uses an app.
3. Uses a feature requiring an API call.

Each of those journeys will be unconnected and not grouped.

To associate those journeys with each other, you can deanonymize the Customer. Deanonymizing will allow for a deeper analysis of a particular user.

Deanonymizing is optional. Basic matching of the customer journey with outcomes is valuable by itself. Deanonymizing will add increased insight as it connects Customer Journeys across devices.

Step 9 - Analysis

Once you have released your instrumented code, you can head to XenonView to view the analytics.

Step 10 - Perform Experiments

There are multiple ways you can experiment using XenonView. We"ll focus here on three of the most common: time, platform, and variant based cohorts.

Time-based cohorts

Each Outcome and Milestone is timestamped. You can use this during the analysis phase to compare timeframes. A typical example is making a feature change. Knowing when the feature went to production, you can filter in the XenonView UI based on the timeframe before and the timeframe after to observe the results.

Variant-based cohorts

You can identify a journey collection as an experiment before collecting data. This will allow you to run A/B testing-type experiments (of course not limited to two). As an example, let"s say you have two alternate content/feature variants and you have a way to direct half of the users to Variant A and the other half to Variant B. You can name each variant before the section of code that performs that journey. After collecting the data, you can filter in the XenonView UI based on each variant to observe the results.

Platform-based cohorts

You can Platform any journey collection before collecting data. This will allow you to experiment against different platforms:

• Operating System Name
• Operating System version
• Device model (Pixel, iPhone 14, Docker Container, Linux VM, Dell Server, etc.)
• A software version of your application.

As an example, let's say you have an iPhone and Android mobile application and you want to see if an outcome is more successful on one device verse the other. You can platform before the section of code that performs that flow. After collecting the data, you can filter in the XenonView UI based on each platform to observe the results.

back to top

Detailed Usage

The following section gives detailed usage instructions and descriptions. It provides code examples for each of the calls.

Installation

You can install the Xenon View SDK from Github:

Via Swift Package Manager

Add to your dependencies section:

dependencies: [
        // Dependencies declare other packages that this package depends on.
        // .package(url: /* package url */, from: "1.0.0"),
        .package(url:"https://github.com/xenonview-com/view-swift-sdk", from: "0.1.0"),
        ...

Then including as a dependency in your app in the targets section:

    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages this package depends on.
        .target(
            name: "<your app name>",
            dependencies: ["xenon_view_sdk"]),

Via Xcode (per version 14)

1. Right-click on your top-level project and select Add Packages...:

2. Paste into the search bar https://github.com/xenonview-com/view-swift-sdk and click Add Package:

3. Select xenon_view_sdk and click Add Package:

4. Ensure Xenon SDK is installed by viewing Package Dependencies:

back to top

Instantiation

The View SDK is a Swift package you'll need to include in your application. After inclusion, you'll need to init the singleton object:

import xenon_view_sdk

// start by initializing Xenon View
Xenon().initialize(apiKey:"<API KEY>")

Typically, this would be done during app initialization:

import xenon_view_sdk

@main
struct ExampleApp: App {
    // register initial Xenon parameters every launch
    init() {
        // start by initializing Xenon View
        Xenon().initialize(apiKey:"<API KEY>")
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Of course, you'll have to make the following modifications to the above code:

• Replace <API KEY> with your api key

Note: For older OS support, surround your calls with:

if #available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *) {
    Xenon().initialize(apiKey:"<API KEY>")
}

back to top

Service/Subscription/SaaS Related Business Outcomes

Lead Capture

Use this call to track Lead Capture (emails, phone numbers, etc.) You can add a specifier string to the call to differentiate as follows:

leadCaptured()

import xenon_view_sdk

let emailSpecified = "Email"
let phoneSpecified = "Phone Number"

// Successful Lead Capture of an email
try! Xenon().leadCaptured(specifier: emailSpecified)
//...
// Successful Lead Capture of a phone number
try! Xenon().leadCaptured(specifier: phoneSpecified)

leadCaptureDeclined()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let emailSpecified = "Email"
let phoneSpecified = "Phone Number"

// Unsuccessful Lead Capture of an email
try! Xenon().leadCaptureDeclined(specifier: emailSpecified)
// ...
// Unsuccessful Lead Capture of a phone number
try! Xenon().leadCaptureDeclined(specifier: phoneSpecified)

Account Signup

Use this call to track when customers signup for an account. You can add a specifier string to the call to differentiate as follows:

accountSignup()

import xenon_view_sdk

let Facebook = "Facebook"
let Google = "Facebook"
let Email = "Email"

// Successful Account Signup with Facebook
try! Xenon().accountSignup(specifier: Facebook)
// ...
// Successful Account Signup with Google
try! Xenon().accountSignup(specifier: Google)
// ...
// Successful Account Signup with an Email
try! Xenon().accountSignup(specifier: Email)

accountSignupDeclined()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let Facebook = "Facebook"
let Google = "Facebook"
let Email = "Email"

// Unsuccessful Account Signup with Facebook
try! Xenon().accountSignupDeclined(specifier: Facebook)
// ...
// Unsuccessful Account Signup with Google
try! Xenon().accountSignupDeclined(specifier: Google)
// ...
// Unsuccessful Account Signup with an Email
try! Xenon().accountSignupDeclined(specifier: Email)

Application Installation

Use this call to track when customers install your application.

applicationInstalled()

import xenon_view_sdk

// Successful Application Installation
try! Xenon().applicationInstalled()

applicationNotInstalled()

:memo: Note: You want consistency between success and failure.

import xenon_view_sdk

// Unsuccessful or not completed Application Installation
try! Xenon().applicationNotInstalled()

Initial Subscription

Use this call to track when customers initially subscribe. You can add a specifier string to the call to differentiate as follows:

initialSubscription()

import xenon_view_sdk

let Silver = "Silver Monthly"
let Gold = "Gold"
let Platium = "Platium"
let annualSilver = "Silver Annual"
let method = "Stripe" // optional
let price = "$25" // optional
let term = "30d" // optional

// Successful subscription of the lowest tier with Stripe
try! Xenon().initialSubscription(tier: Silver, method: method)

// Successful subscription of the lowest tier with Stripe for $25 for term
try! Xenon().initialSubscription(tier: Silver, method: method, price: price, term:term)
// ...
// Successful subscription of the middle tier
try! Xenon().initialSubscription(tier: Gold)
// ...
// Successful subscription to the top tier
try! Xenon().initialSubscription(tier: Platium)
// ...
// Successful subscription of an annual period
try! Xenon().initialSubscription(tier: annualSilver)

subscriptionDeclined()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let Silver = "Silver Monthly"
let Gold = "Gold"
let Platium = "Platium"
let annualSilver = "Silver Annual"
let method = "Stripe" // optional
let price = "$25" // optional
let term = "30d" // optional

// Unsuccessful subscription of the lowest tier
try! Xenon().subscriptionDeclined(tier: Silver)
// ...
// Unsuccessful subscription of the middle tier
try! Xenon().subscriptionDeclined(tier: Gold)
// ...
// Unsuccessful subscription to the top tier
try! Xenon().subscriptionDeclined(tier: Platium)
// ...
// Unsuccessful subscription of an annual period
try! Xenon().subscriptionDeclined(tier: annualSilver, method: method)
// ...
// Unsuccessful subscription of an annual period for $25 for term
try! Xenon().subscriptionDeclined(tier: annualSilver, method: method, price: price, term: term)

Subscription Renewal

Use this call to track when customers renew. You can add a specifier string to the call to differentiate as follows:

subscriptionRenewed()

import xenon_view_sdk

let Silver = "Silver Monthly"
let Gold = "Gold"
let Platium = "Platium"
let annualSilver = "Silver Annual"
let method = "Stripe" //optional
let price = "$25" //optional
let term = "30d" //optional

// Successful renewal of the lowest tier with Stripe
try! Xenon().subscriptionRenewed(tier: Silver, method: method)
// ...
// Successful renewal of the lowest tier with Stripe for $25 for term
try! Xenon().subscriptionRenewed(tier: Silver, method: method, price: price, term: term)
// ...
// Successful renewal of the middle tier
try! Xenon().subscriptionRenewed(tier: Gold)
// ...
// Successful renewal of the top tier
try! Xenon().subscriptionRenewed(tier: Platium)
// ...
// Successful renewal of an annual period
try! Xenon().subscriptionRenewed(tier: annualSilver)

subscriptionCanceled()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let tierSilver = "Silver Monthly"
let tierGold = "Gold"
let tierPlatium = "Platium"
let annualSilver = "Silver Annual"
let method = "Stripe" //optional
let price = "$25" //optional
let term = "30d" //optional

// Canceled subscription of the lowest tier
try! Xenon().subscriptionCanceled(tier: Silver)
// ...
// Canceled subscription of the middle tier
try! Xenon().subscriptionCanceled(tier: Gold)
// ...
// Canceled subscription of the top tier
try! Xenon().subscriptionCanceled(tier: Platium)
// ...
// Canceled subscription of an annual period with Stripe
try! Xenon().subscriptionCanceled(tier: annualSilver, method: method)
// ...
// Canceled subscription of an annual period with Stripe for $25
try! Xenon().subscriptionCanceled(tier: annualSilver, method: method, price: price, term: term)

subscriptionPaused()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let tierSilver = "Silver Monthly"
let tierGold = "Gold"
let tierPlatium = "Platium"
let annualSilver = "Silver Annual"
let method = "Stripe" //optional
let price = "$25" //optional
let term = "30d" //optional

// Paused subscription of the lowest tier
try! Xenon().subscriptionPaused(tier: Silver)
// ...
// Paused subscription of the middle tier
try! Xenon().subscriptionPaused(tier: Gold)
// ...
// Paused subscription of the top tier
try! Xenon().subscriptionPaused(tier: Platium)
// ...
// Paused subscription of an annual period with Stripe
try! Xenon().subscriptionPaused(tier: annualSilver, method: method)
// ...
// Paused subscription of an annual period with Stripe for $25
try! Xenon().subscriptionPaused(tier: annualSilver, method: method, price: price, term: term)

Subscription Upsold

Use this call to track when a Customer upgrades their subscription.
You can add a specifier string to the call to differentiate as follows:

subscriptionUpsold()

import xenon_view_sdk

let Gold = "Gold Monthly"
let Platium = "Platium"
let annualGold = "Gold Annual"
let method = "Stripe" // optional
let price = "$25" // optional
let term = "30d" // optional

// Assume already subscribed to Silver

// Successful upsell of the middle tier with Stripe
try! Xenon().subscriptionUpsold(tier: Gold, method: method)
// ...
// Successful upsell of the middle tier with Stripe for $25 for term
try! Xenon().subscriptionUpsold(tier: Gold, method: method, price: price, term: term)
// ...
// Successful upsell of the top tier
try! Xenon().subscriptionUpsold(tier: Platium)
// ...
// Successful upsell of middle tier - annual period
try! Xenon().subscriptionUpsold(tier: annualGold)

subscriptionUpsellDeclined()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let Gold = "Gold Monthly"
let Platium = "Platium"
let annualGold = "Gold Annual"
let method = "Stripe" //optional
let price = "$25" //optional
let term = "30d" //optional

// Assume already subscribed to Silver

// Rejected upsell of the middle tier
try! Xenon().subscriptionUpsellDeclined(tier: Gold)
// ...
// Rejected upsell of the top tier
try! Xenon().subscriptionUpsellDeclined(tier: Platium)
// ...
// Rejected upsell of middle tier - annual period with Stripe
try! Xenon().subscriptionUpsellDeclined(tier: annualGold, method: method)
// ...
// Rejected upsell of middle tier - annual period with Stripe for $25 for term
try! Xenon().subscriptionUpsellDeclined(tier: annualGold, method: method, price: price, term: term)

subscriptionDownsell()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let Gold = "Gold Monthly"
let Platium = "Platium"
let annualGold = "Gold Annual"
let method = "Stripe" //optional
let price = "$25" //optional
let term = "30d" //optional

// Assume already subscribed to Platium

// Downsell to Gold
try! Xenon().subscriptionDownsell(tier: Gold)
// ...
// Downsell to Gold annual with method
try! Xenon().subscriptionDownsell(tier: annualGold, method: method)
// ...
// Downsell to Gold - annual period with Stripe for $15 for term
try! Xenon().subscriptionDownsell(tier: annualGold, method: method, price: price, term: term)

Ad Clicked

Use this call to track when customers click on an Advertisement. You can add a specifier string to the call to differentiate as follows:

import xenon_view_sdk

let provider = "AdMob"
let id = "ID-1234" //optional
let price = "$0.25" //optional

// Click an Ad from AdMob
try! Xenon().adClicked(provider: provider)
// ...
// Click an Ad from AdMob identified by ID-1234
try! Xenon().adClicked(provider: provider, id: id)
// ...
// Click an Ad from AdMob identified by ID-1234 with price
try! Xenon().adClicked(provider: provider, id: id, price: price)

adIgnored()

import xenon_view_sdk

let provider = "AdMob"
let id = "ID-1234" //optional
let price = "$0.25" //optional

// No action on an Ad from AdMob
try! Xenon().adIgnored(provider: provider)
// ...
// No action on an Ad from AdMob identified by ID-1234
try! Xenon().adIgnored(provider: provider, id: id)
// ...
// No action on an Ad from AdMob identified by ID-1234 with price
try! Xenon().adIgnored(provider: provider, id: id, price: price)

Referral

Use this call to track when customers refer someone to your offering. You can add a specifier string to the call to differentiate as follows:

referral()

import xenon_view_sdk

let kind = "Share"
let detail = "Review" // optional

// Successful referral by sharing a review
try! Xenon().referral(kind: kind, detail: detail)
// -OR-
try! Xenon().referral(kind: kind)

referralDeclined()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let kind = "Share"
let detail = "Review" // optional

//Customer declined referral
try! Xenon().referralDeclined(kind: kind, detail: detail)
// -OR-
try! Xenon().referralDeclined(kind: kind)

back to top

Ecommerce Related Outcomes

Lead Capture

Use this call to track Lead Capture (emails, phone numbers, etc.) You can add a specifier string to the call to differentiate as follows:

leadCaptured()

import xenon_view_sdk

let emailSpecified = "Email"
let phoneSpecified = "Phone Number"

// Successful Lead Capture of an email
try! Xenon().leadCaptured(specifier: emailSpecified)
//...
// Successful Lead Capture of a phone number
try! Xenon().leadCaptured(specifier: phoneSpecified)

leadCaptureDeclined()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let emailSpecified = "Email"
let phoneSpecified = "Phone Number"

// Unsuccessful Lead Capture of an email
try! Xenon().leadCaptureDeclined(specifier: emailSpecified)
// ...
// Unsuccessful Lead Capture of a phone number
try! Xenon().leadCaptureDeclined(specifier: phoneSpecified)

Account Signup

Use this call to track when customers signup for an account. You can add a specifier string to the call to differentiate as follows:

accountSignup()

import xenon_view_sdk

let Facebook = "Facebook"
let Google = "Facebook"
let Email = "Email"

// Successful Account Signup with Facebook
try! Xenon().accountSignup(specifier: Facebook)
// ...
// Successful Account Signup with Google
try! Xenon().accountSignup(specifier: Google)
// ...
// Successful Account Signup with an Email
try! Xenon().accountSignup(specifier: Email)

accountSignupDeclined()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let Facebook = "Facebook"
let Google = "Facebook"
let Email = "Email"

// Unsuccessful Account Signup with Facebook
try! Xenon().accountSignupDeclined(specifier: Facebook)
// ...
// Unsuccessful Account Signup with Google
try! Xenon().accountSignupDeclined(specifier: Google)
// ...
// Unsuccessful Account Signup with an Email
try! Xenon().accountSignupDeclined(specifier: Email)

Add Product To Cart

Use this call to track when customers add a product to the cart. You can add a specifier string to the call to differentiate as follows:

productAddedToCart()

import xenon_view_sdk

let laptop = "Dell XPS"
let keyboard = "Apple Magic Keyboard"

// Successful adds a laptop to the cart
try! Xenon().productAddedToCart(product: laptop)
// ...
// Successful adds a keyboard to the cart
try! Xenon().productAddedToCart(keyboard)

productNotAddedToCart()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let laptop = "Dell XPS"
let keyboard = "Apple Magic Keyboard"

// Doesn"t add a laptop to the cart
try! Xenon().productNotAddedToCart(product: laptop)
// ...
// Doesn"t add a keyboard to the cart
try! Xenon().productNotAddedToCart(product: keyboard)

Upsold Additional Products

Use this call to track when you upsell additional product(s) to customers. You can add a specifier string to the call to differentiate as follows:

upsold()

import xenon_view_sdk

let laptop = "Dell XPS"
let keyboard = "Apple Magic Keyboard"
let keyboardValue = "$139" //optional

// upsold a laptop
try! Xenon().upsold(product: laptop)
// ...
// upsold a keyboard with price
try! Xenon().upsold(product: keyboard, price: keyboardValue)

upsellDismissed()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let laptop = "Dell XPS"
let keyboard = "Apple Magic Keyboard"
let keyboardValue = "$139" //optional

// Doesn"t add a laptop during upsell
try! Xenon().upsellDismissed(product: laptop)
// ...
// Doesn't add a keyboard during upsell with price
try! Xenon().upsellDismissed(product: keyboard, price: keyboardValue)

Customer Checks Out

Use this call to track when your Customer is checking out.

checkedOut()

import xenon_view_sdk

// Successful Checkout
try! Xenon().checkedOut()

checkoutCanceled()

import xenon_view_sdk

//Customer cancels check out.
try! Xenon().checkoutCanceled()

productRemoved()

import xenon_view_sdk

let laptop = "Dell XPS"
let keyboard = "Apple Magic Keyboard"

// Removes a laptop during checkout
try! Xenon().productRemoved(product: laptop)
// ...
// Removes a keyboard during checkout
try! Xenon().productRemoved(product: keyboard)

Customer Completes Purchase

Use this call to track when your Customer completes a purchase.

purchased()

import xenon_view_sdk

let method = "Stripe"
let price = "$2011" // optional

// Successful Purchase
try! Xenon().purchased(method: method)
// ...
// Successful Purchase
try! Xenon().purchased(method: method, price: price)

purchaseCanceled()

import xenon_view_sdk

let method = "Stripe" // optional
let price = "$2011" // optional

//Customer cancels the purchase.
try! Xenon().purchaseCanceled()
// -OR-
try! Xenon().purchaseCanceled(method: method)
// -OR-
try! Xenon().purchaseCanceled(method: method, price: price)

Purchase Shipping

Use this call to track when your Customer receives a purchase.

promiseFulfilled()

import xenon_view_sdk

// Successfully Delivered Purchase
try! Xenon().promiseFulfilled()

promiseUnfulfilled(()

import xenon_view_sdk

// Problem Occurs During Shipping And No Delivery
try! Xenon().promiseUnfulfilled()

Customer Keeps or Returns Product

Use this call to track if your Customer keeps the product. You can add a specifier string to the call to differentiate as follows:

productKept()

import xenon_view_sdk

let laptop = "Dell XPS"
let keyboard = "Apple Magic Keyboard"

//Customer keeps a laptop
try! Xenon().productKept(product: laptop)
// ...
//Customer keeps a keyboard
try! Xenon().productKept(product: keyboard)

productReturned()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let laptop = "Dell XPS"
let keyboard = "Apple Magic Keyboard"

//Customer returns a laptop
try! Xenon().productReturned(product: laptop)
// ...
//Customer returns a keyboard
try! Xenon().productReturned(product: keyboard)

Referrals

Use this call to track when customers refer someone to your offering. You can add a specifier string to the call to differentiate as follows:

referral()

import xenon_view_sdk

let kind = "Share"
let detail = "Review" // optional

// Successful referral by sharing a review
try! Xenon().referral(kind: kind, detail: detail)
// -OR-
try! Xenon().referral(kind: kind)

referralDeclined()

:memo: Note: You want to be consistent between success and failure and match the specifiers

import xenon_view_sdk

let kind = "Share"
let detail = "Review" // optional

//Customer declined referral
try! Xenon().referralDeclined(kind: kind, detail: detail)
// -OR-
try! Xenon().referralDeclined(kind: kind)

back to top

Customer Journey Milestones

As a customer interacts with your brand (via Advertisements, Marketing Website, Product/Service, etc.), they journey through a hierarchy of interactions. At the top level are business outcomes. In between Outcomes, they may achieve other milestones, such as interacting with content and features. Proper instrumentation of these milestones can establish correlation and predictability of business outcomes.

As of right now, Customer Journey Milestones break down into two categories:

1. Feature Usage
2. Content Interaction

Feature Usage

Features are your product/application/service's traits or attributes that deliver value to your customers. They differentiate your offering in the market. Typically, they are made up of and implemented by functions.

featureAttempted()

Use this function to indicate the start of feature usage.

import xenon_view_sdk

let name = "Scale Recipe"
let detail = "x2" // optional

//Customer initiated using a feature
try! Xenon().featureAttempted(feature: name, detail: detail)
// -OR-
try! Xenon().featureAttempted(feature: name)

featureCompleted()

Use this function to indicate the successful completion of the feature.

import xenon_view_sdk

let name = "Scale Recipe"
let detail = "x2" // optional

// ...
// Customer used a feature
try! Xenon().featureCompleted(feature: name, detail: detail)

// -OR-

// Customer initiated using a feature
try! Xenon().featureAttempted(feature: name, detail: detail)
// ...
// feature code/function calls
// ...
// feature completes successfully
try! Xenon().featureCompleted(feature: name, detail: detail)
// -OR-
try! Xenon().featureCompleted(feature: name)

featureFailed()

Use this function to indicate the unsuccessful completion of a feature being used (often in the exception handler).

import xenon_view_sdk


let name = "Scale Recipe"
let detail = "x2" // optional


//Customer initiated using a feature
try! Xenon().featureAttempted(feature: name, detail: detail)
try {
  // feature code that could fail
}
catch(err) {
  //feature completes unsuccessfully
  try! Xenon().featureFailed(feature: name, detail: detail)
  // -OR-
  try! Xenon().featureFailed(feature: name)
}

back to top

Content Interaction

Content is created assets/resources for your site/service/product. It can be static or dynamic. You will want to mark content that contributes to your Customer's experience or buying decision. Typical examples:

• Blog
• Blog posts
• Video assets
• Comments
• Reviews
• HowTo Guides
• Charts/Graphs
• Product/Service Descriptions
• Surveys
• Informational product

contentViewed()

Use this function to indicate a view of specific content.

import xenon_view_sdk

let contentType = "Blog Post"
let identifier = "how-to-install-xenon-view" // optional

// Customer view a blog post
try! Xenon().contentViewed(type: contentType, identifier: identifier)
// -OR-
try! Xenon().contentViewed(type: contentType)

contentEdited()

Use this function to indicate the editing of specific content.

import xenon_view_sdk

let contentType = "Review"
let identifier = "Dell XPS" //optional
let detail = "Rewrote" //optional

//Customer edited their review about a laptop
try! Xenon().contentEdited(type: contentType, identifier: identifier, detail: detail)
// -OR-
try! Xenon().contentEdited(type: contentType, identifier: identifier)
// -OR-
try! Xenon().contentEdited(type: contentType)

contentCreated()

Use this function to indicate the creation of specific content.

import xenon_view_sdk

let contentType = "Blog Comment"
let identifier = "how-to-install-xenon-view" // optional

//Customer wrote a comment on a blog post
try! Xenon().contentCreated(type: contentType, identifier: identifier)
// -OR-
try! Xenon().contentCreated(type: contentType)

contentDeleted()

Use this function to indicate the deletion of specific content.

import xenon_view_sdk

let contentType = "Blog Comment"
let identifier = "how-to-install-xenon-view" // optional

//Customer deleted their comment on a blog post
try! Xenon().contentDeleted(type: contentType, identifier: identifier)
// -OR-
try! Xenon().contentDeleted(type: contentType)

contentArchived()

Use this function to indicate archiving specific content.

import xenon_view_sdk

let contentType = "Blog Comment"
let identifier = "how-to-install-xenon-view" // optional

//Customer archived their comment on a blog post
try! Xenon().contentArchived(type: contentType, identifier: identifier)
// -OR-
try! Xenon().contentArchived(type: contentType)

contentRequested()

Use this function to indicate the request for specific content.

import xenon_view_sdk

let contentType = "Info Product"
let identifier = "how-to-efficiently-use-google-ads" // optional

//Customer requested some content
try! Xenon().contentRequested(type: contentType, identifier: identifier)
// -OR-
try! Xenon().contentRequested(type: contentType)

contentSearched()

Use this function to indicate when a user searches.

import xenon_view_sdk

let contentType = "Info Product"

// Customer searched for some content
try! Xenon().contentSearched(type: contentType)

back to top

Commit Points

Business Outcomes and Customer Journey Milestones are tracked locally in memory until you commit them to the Xenon View system. After you have created (by either calling a milestone or outcome) a customer journey, you can commit it to Xenon View for analysis as follows:

commit()

This call commits a customer journey to Xenon View for analysis.

import xenon_view_sdk

// you can commit a journey to Xenon View
try! Xenon().commit()

back to top

Heartbeats

Business Outcomes and Customer Journey Milestones are tracked locally in memory until you commit them to the Xenon View system. You can use the heartbeat call if you want to commit in batch. Additionally, the heartbeat call will update a last-seen metric for customer journeys that have yet to arrive at Business Outcome. The last-seen metric is useful when analyzing stalled Customer Journeys.

Usage is as follows:

heartbeat()

import xenon_view_sdk

// you can heartbeat to Xenon View
try! Xenon().heartbeat()

This call commits any uncommitted journeys to Xenon View for analysis and updates the last accessed time.

back to top

Platforming

After you have initialized View, you can optionally specify platform details such as:

• Operating System Name
• Operating System version (iOS) See OperatingSystemVersion
• Device model (iPhone, iPad, etc.) See DeviceKit
• Software version of your application.

platform()

import xenon_view_sdk

let softwareVersion = "x.y.z" // use your app version
let deviceModel = "iPhone 11 Pro"
let operatingSystemVersion = "16.0.2"
let operatingSystemName = "iOS"

// you can add platform details to outcomes
try! Xenon().platform(softwareVersion: softwareVersion, deviceModel: deviceModel, operatingSystemVersion: operatingSystemVersion)

This adds platform details for each outcome. Typically, this would be set once at initialization:

import DeviceKit
import xenon_view_sdk

@main
struct ExampleApp: App {
    // register initial Xenon parameters every launch
    init() {
        // start by initializing Xenon View
        Xenon().initialize(apiKey:"<API KEY>")
        let os = ProcessInfo().operatingSystemVersion
        let softwareVersion = "5.1.5"
        let deviceModel = "\(Device.current)"
        let operatingSystemVersion = "\(os.majorVersion).\(os.minorVersion).\(os.patchVersion)"
        let operatingSystemName = ProcessInfo().operatingSystemVersionString

        try! try! Xenon().platform(softwareVersion: softwareVersion, deviceModel: deviceModel, operatingSystemName: operatingSystemName, operatingSystemVersion: operatingSystemVersion)
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

back to top

Experiments

After you have initialized Xenon View, you can optionally name variants of customer journeys. Named variants facilitate running experiments such as A/B or split testing.

:memo: Note: You are not limited to just 2 (A or B); there can be many. Additionally, you can have multiple variant names.

variant()

import xenon_view_sdk

let variantName = "subscription-variant-A"

// you can add platform details to outcomes
try! Xenon().variant(names: [variantName])

This adds variant names to each outcome while the variant in play (Saas/Ecom). Typically, you would name a variant once you know the active experiment for this Customer:

import xenon_view_sdk

@main
struct ExampleApp: App {
    // register initial Xenon parameters every launch
    init() {
        // start by initializing Xenon View
        Xenon().initialize(apiKey:"<API KEY>")
        let experimentName = getExperiment()
        try! Xenon().variant(names: [experimentName])
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

resetVariants()

import xenon_view_sdk

// you can clear all variant names with the resetVariants method
try! Xenon().resetVariants()

back to top

Customer Journey Grouping

Xenon View supports both anonymous and grouped (known) journeys.

All the customer journeys (milestones and outcomes) are anonymous by default. For example, if a Customer interacts with your brand in the following way:

1. Starts on your marketing website.
2. Downloads and uses an app.
3. Uses a feature requiring an API call.

Each of those journeys will be unconnected and not grouped.

To associate those journeys with each other, you can use deanonymize(). Deanonymizing will allow for a deeper analysis of a particular user.

Deanonymizing is optional. Basic matching of the customer journey with outcomes is valuable by itself. Deanonymizing will add increased insight as it connects Customer Journeys across devices.

Usage is as follows:

deanonymize()

import xenon_view_sdk

// you can deanonymize before or after you have committed journey (in this case after):
let person = [
    "name": "Test User",
    "email": "[email protected]"
]
try! await opSubject.deanonymize(person: person)

// you can also deanonymize with a user ID:
let person = [
  "UUID": "<some unique ID>"
]
try! await opSubject.deanonymize(person: person)

This call deanonymizes every journey committed to a particular user.

:memo: Note: With journeys that span multiple platforms (e.g., Website->Android->API backend), you can group the Customer Journeys by deanonymizing each.

back to top

Other Operations

There are various other operations that you might find helpful:

Error handling

In the event of an API error, an exception occurs with the response from the API as Requests response object:

:memo: Note: The default handling of this situation will restore the journey (appending newly added pageViews, events, etc.) for future committing. If you want to do something special, you can do so like this:

import xenon_view_sdk

// you can handle errors if necessary
do {
    let result = try await opSubject.commit().value
    switch result {
    case .success(let dictionary):
        print(dictionary)
    case .failure(let error):
        //... handle server side error ...
        print(error)
    }
} catch {
    //... handle local error ...
    print(error)
}

Custom Milestones

You can add custom milestones if you need more than the current Customer Journey Milestones.

milestone()

import xenon_view_sdk

// you can add a custom milestone to the customer journey
let category = "Function"
let operation = "Called"
let name = "Query Database"
let detail = "User Lookup"
try! Xenon().milestone(category: category, operation: operation, name: name, detail: detail)

This call adds a custom milestone to the customer journey.

Journey IDs

Each Customer Journey has an ID akin to a session. After committing an Outcome, the ID remains the same to link all the Journeys. If you have a previous Customer Journey in progress and would like to append to that, you can get/set the ID.

:memo: Note: For Swift, the Journey ID is a persistent session variable. Therefore, subsequent Outcomes will reuse the Journey ID if one is available.

After you have initialized the Xenon singleton, you can:

1. Use the default UUID
2. Set the Customer Journey (Session) ID
3. Regenerate a new UUID
4. Retrieve the Customer Journey (Session) ID

id()

import xenon_view_sdk
// by default has Journey id
expect(Xenon().id()).notTo(beNil())
expect(Xenon().id()).notTo(equal(""))

// you can also set the id
let testId = "<some random uuid>"
Xenon().id(_id: testId)


// lastly you can generate a new one (useful for serialized async operations that are for different customers)
Xenon().newId()
expect(Xenon().id()).notTo(beNil())
expect(Xenon().id()).notTo(equal(""))

back to top

License

Apache Version 2.0

See LICENSE

back to top