React Native SDK - 跟踪应用程序内事件

关注
Avatar
Dora Kishinevsky
Updated
文档

跟踪应用程序内事件

跟踪应用内事件以分析营销活动绩效并衡量关键绩效指标 (KPI)，如用户登录、注册、教程完成或进度里程碑。

标准事件和属性

了解事件类型

Singular 支持两种类型的事件，以满足通用和特定应用程序的跟踪需求。

  • 标准事件：由 Singular 识别的预定义事件（如sngLogin,sngContentView ），广告网络支持报告和优化。使用标准事件可简化设置，因为 Singular 会自动将其添加到 "事件 "列表中，无需手动定义。有关完整的事件名称和推荐属性，请参阅 "标准事件和属性列表"。
  • 自定义事件：您的应用程序特有的事件（如Signup,AchievementUnlocked ），与 Singular 的标准事件不匹配。

建议尽可能使用标准事件，以便与广告网络兼容，并在 Singular 的事件列表中自动识别。

您的用户体验、营销或业务团队应根据企业的营销 KPI 编制事件列表。请参考《如何跟踪应用内事件》指南：Singular 归因客户指南》进行规划。

自定义事件限制

自定义事件有特定的字符和编码限制，以确保与第三方合作伙伴和分析解决方案的兼容性。

自定义事件限制：

  • 语言：以英文传递事件名称和属性，以确保与第三方合作伙伴和分析解决方案的兼容性。
  • 事件名称：限制为 32 个 ASCII 字符，非 ASCII 字符串转换为 UTF-8 时必须小于 32 字节。
  • 属性和值：限制为 500 个 ASCII 字符

发送事件

事件方法

使用event() 方法跟踪无附加属性的简单事件。

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Track a simple custom event
NativeSingular.event('SignUp');

// Track a standard event using constant
NativeSingular.event('sngLogin');

方法签名： 

static event(eventName: string): void

有关方法的完整列表，请参阅事件方法参考。

EventWithArgs 方法

跟踪带有附加自定义属性的事件，以提供更丰富的上下文，并在报告中进行详细的细分。

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Track custom event with attributes
NativeSingular.eventWithArgs('LevelComplete', {
  level: 5,
  score: 1250,
  time_spent: 45.3
});

// Track standard event with recommended attributes
NativeSingular.eventWithArgs('sngTutorialComplete', {
  sngAttrContent: 'React Native Basics',
  sngAttrContentId: '32',
  sngAttrContentType: 'video',
  sngAttrSuccess: 'yes'
});

方法特征： 

static eventWithArgs(eventName: string, args: Record<string, any>): void

有关方法的完整列表，请参阅eventWithArgs 方法参考。

最佳实践

  • 使用标准事件：首选标准事件，以便与广告网络兼容，并在 Singular 的事件列表中自动识别。
  • 验证属性：发送前检查属性是否符合预期格式和字符限制
  • 调试事件：在开发过程中启用 SDK 日志，以验证事件是否正确发送并在适当的时刻触发
  • 与团队协调：与用户体验/营销团队合作，确保跟踪的事件与应用程序的 KPI 保持一致
  • 在生产前进行测试：在开发环境中测试事件，以验证 Singular 控制面板中数据的准确性

跟踪应用内收入

跟踪来自应用内购买 (IAP)、订阅和自定义收入来源的收入，以衡量营销活动的绩效和广告支出回报率 (ROAS)。

收入数据通过三个渠道流动：

  • 互动报告：在 Singular 面板中查看收入指标
  • 导出日志：访问详细的 ETL 数据，进行自定义分析
  • 实时回传：将收入事件发送到外部平台

为什么要跟踪收入事件？

  • 丰富的分析功能：获取详细的交易数据，增强 Singular 报告
  • 预防欺诈：包括交易收据（如来自 Google Play 或 Apple App Store 的收据），以验证购买并打击应用内欺诈行为
  • 营销活动优化：将收入与营销工作挂钩，衡量投资回报率

最佳实践：传递完整的购买对象

我们强烈建议传递从 Android（Google Play 账单）或 iOS（StoreKit）应用内购买（IAP）流程返回的购买对象。 这将确保 Singular 收到全面的交易详细信息，包括

  • 产品 ID
  • 价格
  • 货币
  • 交易 ID
  • 收据数据（用于验证）

通过传递完整的购买对象，您可以获得更丰富的报告，并利用 Singular 的欺诈检测功能，尤其是针对 Google Play 交易。

应用内购买集成

捕获 IAP 购买对象

使用特定平台的 IAP 库检索包含完整交易详细信息的购买对象。

应用内购买方法

利用购买详情跟踪应用内购买事件，以验证收入和防止欺诈。

方法签名： 

static inAppPurchase(eventName: string, purchase: SingularIOSPurchase | SingularAndroidPurchase): void
static inAppPurchaseWithArgs(eventName: string, purchase: SingularIOSPurchase | SingularAndroidPurchase, args: Record<string, any>): void

有关方法的完整列表，请参阅inAppPurchase 方法参考。

完整的 IAP 实现示例

实现完整的购买监听器，捕获 IAP 事件并将其发送到 Singular，同时发送特定于平台的购买对象。

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import { Platform } from 'react-native';
import NativeSingular from 'singular-react-native/jsNativeSingular';
import { 
  SingularIOSPurchase, 
  SingularAndroidPurchase 
} from 'singular-react-native';
import { 
  initConnection,
  getProducts,
  setPurchaseListener,
  finishTransaction,
  IAPResponseCode
} from 'react-native-iap';

// Helper function to convert price to a double
const getPriceAsDouble = (product) => {
  if (Platform.OS === 'android' && product.priceAmountMicros) {
    // Android: Convert priceAmountMicros to double
    return product.priceAmountMicros / 1000000.0;
  } else if (Platform.OS === 'ios') {
    // iOS: Parse price string (e.g., "$4.99" -> 4.99)
    const priceString = product.price.replace(/[^0-9.]/g, '');
    return parseFloat(priceString) || 0.0;
  }
  return 0.0; // Fallback
};

// Set up purchase listener
const handlePurchases = async () => {
  try {
    // Initialize connection
    await initConnection();

    // Set purchase listener
    setPurchaseListener(async ({ responseCode, results }) => {
      if (responseCode === IAPResponseCode.OK) {
        for (const purchase of results) {
          if (!purchase.acknowledged) {
            // Fetch product details
            const products = await getProducts({ skus: [purchase.productId] });
            const product = products.length > 0 ? products[0] : null;
            if (!product) return;

            // Create purchase object
            let singularPurchase = null;

            if (Platform.OS === 'ios') {
              singularPurchase = new SingularIOSPurchase(
                getPriceAsDouble(product),
                product.currency ?? 'USD',
                purchase.productId,
                purchase.transactionId ?? '',
                purchase.transactionReceipt
              );
            } else if (Platform.OS === 'android') {
              const jsonData = JSON.parse(purchase.transactionReceipt || '{}');
              const receipt = jsonData.purchaseToken || '';

              singularPurchase = new SingularAndroidPurchase(
                getPriceAsDouble(product),
                product.currency ?? 'USD',
                purchase.transactionReceipt,
                purchase.signatureAndroid
              );
            } else {
              return;
            }

            // Track in-app purchase
            NativeSingular.inAppPurchase('iap_purchase', singularPurchase);

            // Complete the purchase
            await finishTransaction(purchase, Platform.OS === 'ios');
          }
        }
      }
    });
  } catch (error) {
    console.error('Error handling purchases:', error);
  }
};

// Call handlePurchases when your app starts
handlePurchases();

手动收入跟踪

无需购买验证的收入

通过传递货币、金额和可选产品详细信息来跟踪收入，而无需购买对象。请注意，此方法不提供用于验证的交易收据。

重要：在发送没有有效购买对象的收入事件时，Singular 不会验证交易。我们强烈建议尽可能使用上述inAppPurchase() 方法。

注意：以三个字母的 ISO 4217 货币代码形式传递货币，如USD,EUR,INR 。

收入方法

跟踪具有指定货币和金额的简单收入事件。

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Track revenue without product details
NativeSingular.revenue('USD', 4.99);

方法签名： 

static revenue(currency: string, amount: number): void

有关方法的完整列表，请参阅收入方法参考。

RevenueWithArgs 方法

跟踪带有指定货币、金额和附加自定义属性的收入事件。

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Track revenue with attributes
NativeSingular.revenueWithArgs('USD', 9.98, {
  productSKU: 'coin_package_abc123',
  productName: 'Coin Pack 10',
  productCategory: 'Bundles',
  productQuantity: 2,
  productPrice: 4.99,
  transaction_id: 'T12345'
});

方法签名： 

static revenueWithArgs(currency: string, amount: number, args: Record<string, any>): void

有关方法的完整列表，请参见revenueWithArgs 方法参考。

自定义收入方法

使用指定的事件名称、货币和金额跟踪自定义收入事件。

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Track custom revenue event
NativeSingular.customRevenue('PremiumUpgrade', 'USD', 9.99);

方法签名： 

static customRevenue(eventName: string, currency: string, amount: number): void

有关方法的完整列表，请参见customRevenue 方法参考。

CustomRevenueWithArgs 方法

使用指定的事件名称、货币、金额和其他自定义属性跟踪自定义收入事件。

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Track custom revenue event with attributes
NativeSingular.customRevenueWithArgs('PremiumBundlePurchase', 'USD', 99.99, {
  productSKU: 'premium_bundle_xyz',
  productName: 'Premium Bundle',
  productCategory: 'Bundles',
  productQuantity: 1,
  productPrice: 99.99,
  discount_applied: true
});

方法签名： 

static customRevenueWithArgs(eventName: string, currency: string, amount: number, args: Record<string, any>): void

有关方法的完整列表，请参见customRevenueWithArgs 方法参考。

订阅收入

跟踪订阅

Singular 提供了使用 Singular SDK 实现订阅事件的综合指南。该指南涵盖跨各种平台的应用内订阅事件跟踪。

混合事件跟踪（高级）

Singular 建议通过集成到应用程序中的 Singular SDK 发送所有事件和收入，以获得最佳归因。不过，必要时，Singular 也可以从其他来源收集事件。

在Singular SDK之外发送的事件必须符合Singular的服务器到服务器事件文档要求，并提供匹配的设备标识符，以便正确归因。

重要：

如果服务器到服务器事件请求中使用的设备标识符在 Singular 中没有匹配的设备标识符，就会出现差异。请注意以下可能性：

  • 早期事件：如果在Singular SDK 从应用程序会话中记录设备标识符之前收到事件请求，事件请求将被视为未知设备的 "第一次会话"，Singular 将把设备归属为有机归属。
  • 不匹配的标识符：如果Singular SDK记录了设备标识符，但与服务器到服务器事件请求中指定的设备标识符不同，则事件将被错误归属

混合事件跟踪指南

从内部服务器发送事件

从内部服务器收集收入数据，分析营销活动的绩效和投资回报率。

要求：

  • 捕获设备标识符：从应用内注册或登录事件中捕获并传递设备标识符，并将此数据与服务器上的用户 ID 一起存储。由于用户的设备标识符可能会发生变化，因此应在用户生成应用程序会话时更新标识符。这将确保服务器端事件归属于正确的设备
  • 平台特定标识符：服务器端事件是平台特定的，只能使用与设备平台相匹配的设备标识符发送（例如，iOS 设备使用 IDFA 或 IDFV，Android 设备使用 GAID）
  • 实时更新：使用奇异内部商业智能回传机制将事件实时推送到内部端点，以便在服务器端更新数据集。请参阅内部 BI 回传常见问题
  • 实施细节：查看 "服务器到服务器集成 "指南中的 "跟踪收入"部分了解详情

从收入提供商发送事件

集成 RevenueCat 或 adapty 等第三方收入提供商，向 Singular 发送购买和订阅收入。

支持的供应商：

从Segment发送事件

通过在Segment中添加 "云模式 "目标，使Segment能够与Singular SDK并行发送事件到Singular。

详细设置说明请参阅Singular-Segment Integration实施指南。