Tula SDK Documentation

import TulaSDK from 'tula-js';

const tula = new TulaSDK({
  apiKey: 'your_api_key_here',
  debug: true,                      // Optional: enables debug logging
  batchSize: 10,                    // Optional: event batch size (default: 10)
  flushInterval: 5000,              // Optional: auto-flush interval in ms (default: 5000)
  platform: 'ios'                  // Optional: 'ios' | 'android' | 'both' (auto-detected)
});

// Initialize with player identification
await tula.initialize('player_123', {
  level: 42,
  vip: false,
  country: 'US'
});

// Or let SDK auto-generate player ID
await tula.initialize(); // Auto-generates and persists player ID

<!-- Store page wrapper -->
<div data-tula-store data-tula-properties='{"section": "main"}'>
  <h1>Game Store</h1>
  <!-- Your store UI here -->
</div>

<!-- Individual item elements -->
<div data-tula-item data-tula-variant='{"itemId": "gold_coins", "variant": {...}}'>
  <img src="coins.png" alt="Gold Coins" />
  <p>$0.99 - 100 Coins</p>
  <button>Buy Now</button>
</div>

// Get the optimized variant for a virtual item
const variant = await tula.getItemVariant('coins_pack');

// The variant contains all necessary information
console.log(variant.itemId);                 // Developer-friendly ID: "coins_pack"
console.log(variant.variant.productId);      // App Store/Play Store product ID
console.log(variant.variant.price.formatted); // "$0.99"
console.log(variant.variant.quantity);       // 100
console.log(variant.experimentId);           // Current experiment ID if active
console.log(variant.experimentName);         // Human-readable experiment name
console.log(variant.isExperiment);           // true if part of A/B test
console.log(variant.isControl);              // true if this is the control group

// Experiment view is automatically tracked when getting a variant
// if it's part of an active experiment

import TulaSDK from 'tula-js';

class GameStore {
  constructor() {
    this.tula = new TulaSDK({
      apiKey: process.env.TULA_API_KEY
    });
  }

  async initialize(playerId) {
    await this.tula.initialize(playerId, {
      level: this.getPlayerLevel(),
      vip: this.isVIPPlayer()
    });
    // Auto-tracking starts automatically after initialization
  }

  async loadStoreItems() {
    // Fetch optimized variants for all items
    const variants = [];
    for (const item of this.items) {
      const variant = await this.tula.getItemVariant(item.id);
      variants.push({ ...item, variant });
    }

    // Render store with data attributes for auto-tracking
    this.renderStoreWithAutoTracking(variants);
    return variants;
  }

  renderStoreWithAutoTracking(variants) {
    // Create store container with auto-tracking
    const storeContainer = document.createElement('div');
    storeContainer.setAttribute('data-tula-store', '');
    storeContainer.setAttribute('data-tula-properties', JSON.stringify({
      source: 'main_menu',
      items_count: variants.length
    }));

    variants.forEach((item, index) => {
      const itemElement = document.createElement('div');
      
      // Auto-track item views when element becomes visible
      itemElement.setAttribute('data-tula-item', '');
      itemElement.setAttribute('data-tula-variant', JSON.stringify(item.variant));
      itemElement.setAttribute('data-tula-properties', JSON.stringify({
        position: index + 1,
        category: item.category
      }));

      // Add your item UI
      itemElement.innerHTML = `
        <img src="${item.icon}" alt="${item.name}" />
        <h3>${item.name}</h3>
        <p>${item.variant.variant.price.formatted} - ${item.variant.variant.quantity} ${item.unit}</p>
        <button onclick="purchaseItem('${item.id}')">Buy Now</button>
      `;

      storeContainer.appendChild(itemElement);
    });

    // Store view and item views are automatically tracked!
    document.getElementById('store-root').appendChild(storeContainer);
  }

  async purchaseItem(itemId) {
    const variant = this.getVariantById(itemId);
    
    try {
      // Track purchase start
      await this.tula.trackPurchaseStart(variant);

      // Process purchase...
      const transaction = await this.processPlatformPurchase(variant.variant.productId);

      // Track completion
      await this.tula.trackPurchaseComplete(variant, transaction.id);
      
      return { success: true, transaction };
    } catch (error) {
      // Track failure
      await this.tula.trackPurchaseFail(variant, error.message);
      return { success: false, error };
    }
  }
}

import TulaSDK from 'tula-js';

class GameStore {
  constructor() {
    this.tula = new TulaSDK({
      apiKey: process.env.TULA_API_KEY
    });
    
    // Disable auto-tracking for manual control
    this.tula.disableAutoTracking();
  }

  async initialize(playerId) {
    await this.tula.initialize(playerId, {
      level: this.getPlayerLevel(),
      vip: this.isVIPPlayer(),
      totalSpent: this.getPlayerLifetimeValue()
    });
  }

  async loadStoreItems() {
    // Manually track store view
    await this.tula.logEvent('store_view', {
      source: 'main_menu',
      items_count: this.items.length
    });

    // Get optimized variants for each item
    const variants = [];
    for (const item of this.items) {
      const variant = await this.tula.getItemVariant(item.id);
      variants.push({ ...item, variant });

      // Manually track item view
      await this.tula.logEvent('experiment_view', {
        itemId: variant.itemId,
        skuVariantId: variant.variant.skuVariantId,
        experimentId: variant.experimentId,
        experimentArmId: variant.experimentArmId,
        position: variants.length
      });
    }

    // Track custom events for game-specific metrics
    this.tula.trackCustomEvent('store_loaded', {
      load_time: Date.now() - startTime,
      items_count: variants.length,
      player_level: this.getPlayerLevel()
    });

    return variants;
  }

  async purchaseItem(variant) {
    try {
      // Track purchase start
      await this.tula.trackPurchaseStart(variant);

      // Platform-specific purchase flow
      const transaction = await this.processPlatformPurchase(
        variant.variant.productId
      );

      // Track successful purchase
      await this.tula.trackPurchaseComplete(
        variant, 
        transaction.id,
        {
          receipt: transaction.receipt,
          verified: await this.verifyReceipt(transaction)
        }
      );

      // Grant items to player
      this.grantItems(variant.variant.quantity);

      return { success: true, transaction };

    } catch (error) {
      // Track failed purchase
      await this.tula.trackPurchaseFail(
        variant,
        error.message,
        {
          error_code: error.code,
          step: this.getPurchaseStep(error)
        }
      );

      return { success: false, error };
    }
  }

  async processPlatformPurchase(productId) {
    // Platform-specific implementation
    if (this.platform === 'ios') {
      return await this.processStoreKitPurchase(productId);
    } else if (this.platform === 'android') {
      return await this.processPlayBillingPurchase(productId);
    }
  }
}