spectacles-commerce

name

spectacles-commerce

description

Reference guide for CommerceKit and In-App Purchases on Spectacles — covering CommerceKitModule initialization, converting prices to integer cents, editor mock purchases versus device production purchases, queryPurchaseHistory for ownership checking, launchPurchaseFlow to prompt a swipe-to-buy, acknowledgePurchase to verify consumption, and handling UserCanceled responses. Use this skill when building premium lenses, freemium features, unlocking levels, or selling non-consumable digital items on the Snap platform.

Spectacles CommerceKit — Reference Guide

CommerceKit enables handling in-app purchases (IAP) for non-consumable digital items directly inside Custom Lenses on Spectacles.

Note: Commerce capabilities are in Closed Beta and require your Lens Studio account to have proper onboarding.

---

Setup & Architecture

Commerce uses the CommerceKitModule. You define a local "Product Catalog" representing the items you are selling.

Prices in CommerceKit APIs are always expected in Integer Cents (e.g. $2.99 is passed as 299).

---

1. Creating the Commerce Client

Initialize the client with your catalog. You must provide a callback to handle asynchronous purchase results.

const commerceModule = require("LensStudio:CommerceKitModule") as CommerceKitModule
let commerceClient: Commerce.Client

// Define your products
const catalog = [
  { id: "premium_skin_01", displayName: "Gold Skin", price: { currency: "USD", price: 299 } },
  { id: "level_pack_02", displayName: "Extra Levels", price: { currency: "USD", price: 499 } }
]

const clientOptions = new Commerce.ClientOptions((result, purchases) => {
  onPurchasesUpdated(result, purchases)
})

// Embed the catalog as JSON in the extras
clientOptions.extras = JSON.stringify({ productCatalog: catalog })

// Create client
commerceClient = commerceModule.createClient(clientOptions)

// Connect to the commerce backend
commerceClient.startConnection()
  .then(async () => {
    print("Commerce connection started.")
    await refreshOwnership()
  })
  .catch((e) => print("Commerce connection failed: " + e))

---

2. Checking Ownership History

Before offering a purchase, query the user's history to see if they already own it.

const ownedProducts = new Map<string, Commerce.PurchaseState>()

async function refreshOwnership() {
  const history = await commerceClient.queryPurchaseHistory()
  
  ownedProducts.clear()
  history.forEach((purchase) => {
    // purchaseState can be: Purchased, Pending, Unset
    ownedProducts.set(purchase.productId, purchase.purchaseState)
    print(`Product ${purchase.productId} is ${purchase.purchaseState}`)
  })
}

function isProductOwned(productId: string): boolean {
  return ownedProducts.get(productId) === Commerce.PurchaseState.Purchased
}

---

3. Launching the Purchase Flow

When a user taps a "Buy" button, attempt to launch the flow.

async function buyProduct(productId: string) {
  // 1. Editor mock check
  if (global.deviceInfoSystem.isEditor()) {
    print(`Mock purchase completed for ${productId} (Editor mode)`)
    ownedProducts.set(productId, Commerce.PurchaseState.Purchased)
    return
  }

  // 2. Already owned?
  if (isProductOwned(productId)) {
    print("User already owns this.")
    return
  }
  
  // 3. Launch flow
  const result = await commerceClient.launchPurchaseFlow(productId)
  if (result.responseCode !== Commerce.ResponseCode.Success) {
    print("Failed to launch flow: " + result.responseCode)
  }
  // The result will bubble up to the onPurchasesUpdated callback.
}

---

4. Handling the Purchase Callback

The ClientOptions callback receives results from the system purchase overlay. A purchase isn't finalized until you acknowledge it.

async function onPurchasesUpdated(result: Commerce.PurchaseResult, purchases: Commerce.Purchase[]) {
  if (!purchases || purchases.length === 0) return

  switch (result.responseCode) {
    case Commerce.ResponseCode.Success:
      for (const p of purchases) {
         if (p.token) await finalizePurchase(p.token)
      }
      break
      
    case Commerce.ResponseCode.UserCanceled:
      print("User cancelled the purchase flow.")
      break
      
    default:
      print(`Purchase error: Code ${result.responseCode}`)
      break
  }
  
  // Always refresh logic to ensure sync
  await refreshOwnership()
}

Acknowledging the Purchase

async function finalizePurchase(token: string) {
  try {
    const ackResult = await commerceClient.acknowledgePurchase(token)
    if (ackResult.responseCode === Commerce.ResponseCode.Success) {
      print("Purchase verified and acknowledged successfully!")
      // Unlock content in the lens here
    }
  } catch (err) {
    print("Failed to acknowledge purchase: " + err)
  }
}

---

Common Gotchas

• Cent conversion: Always multiply floating-point dollars by 100 and use Math.round() prior to passing to CommerceKit to avoid floating point drift. (e.g. Math.round(2.99 * 100)).
• Editor Mode: Commerce flows do not launch in Lens Studio editor. Mock your purchases by checking global.deviceInfoSystem.isEditor() and faking an immediate "Owned" state.
• Pending States: queryPurchaseHistory might return Commerce.PurchaseState.Pending if network failed halfway. You should attempt to re-acknowledge pending items on startup.

---

Reference Examples

• CommerceKit.ts - Core singleton client wrapping CommerceKitModule.
• ExamplePurchaseController.ts - A comprehensive implementation example.