アプリ内イベントのトラッキング

アプリ内イベントをトラッキングして、キャンペーンのパフォーマンスを分析し、ユーザーのログイン、登録、チュートリアル完了、進行状況のマイルストーンなどの主要業績評価指標（KPI）を測定します。

標準イベントと属性

イベントタイプの理解

Singularは、汎用的なトラッキングニーズとアプリ固有のトラッキングニーズの両方に対応するため、2種類のイベントをサポートしています。

標準イベント： Singularによって認識され、レポートと最適化のために広告ネットワークでサポートされている定義済みのイベント（例： sngLogin 、 sngContentView ）。標準イベントを使用すると、Singularが手動での定義なしにイベントリストへ自動的に追加するため、セットアップが簡素化されます。完全なイベント名と推奨属性については、標準イベントと属性の一覧を参照してください。
カスタムイベント： Singularの標準イベントに一致しない、アプリ固有のイベント（例： Signup 、 AchievementUnlocked ）。

推奨事項： 広告ネットワークとの互換性と、Singularのイベントリストでの自動認識のために、可能な限り標準イベントを使用してください。

UA、マーケティング、またはビジネスチームが、組織のマーケティングKPIに基づいてイベントの一覧を作成する必要があります。計画にあたっては、ガイドアプリ内イベントのトラッキング方法：Singularアトリビューション顧客向けガイドを参照してください。

カスタムイベントの制限

カスタムイベントには、サードパーティパートナーおよび分析ソリューションとの互換性を確保するため、特定の文字数およびエンコーディングの制約があります。

カスタムイベントの制限：

言語： サードパーティパートナーおよび分析ソリューションとの互換性を確保するため、イベント名と属性は英語で渡してください
イベント名： 32文字のASCII文字に制限されます。非ASCII文字列は、UTF-8に変換したときに32バイト未満である必要があります
属性と値： 500文字のASCII文字に制限されます

イベントの送信

Eventメソッド

追加の属性を持たないシンプルなイベントは、 event() メソッドを使用してトラッキングします。

import 'package:singular_flutter_sdk/singular.dart';

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

// Track a standard event
Singular.event('sngLogin');

メソッドシグネチャ：

static void event(String eventName)

メソッドの完全な一覧については、 eventメソッドリファレンスを参照してください。

EventWithArgsメソッド

追加のカスタム属性を持つイベントをトラッキングすることで、より豊富なコンテキストを提供し、レポートでの詳細なセグメンテーションを可能にします。

import 'package:singular_flutter_sdk/singular.dart';

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

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

メソッドシグネチャ：

static void eventWithArgs(String eventName, Map args)

メソッドの完全な一覧については、 eventWithArgsメソッドリファレンスを参照してください。

ベストプラクティス

標準イベントを使用する： 広告ネットワークとの互換性と、Singularのイベントリストでの自動認識のために、標準イベントを優先してください
属性を検証する： 送信前に、属性が想定される形式と文字数制限に一致していることを確認してください
イベントをデバッグする： 開発中はSDKロギングを有効にして、イベントが正しく送信され、適切なタイミングでトリガーされていることを確認してください
チームと連携する： UA/マーケティングチームと協力して、トラッキングするイベントがアプリのKPIと整合していることを確認してください
本番環境の前にテストする： 開発環境でイベントをテストして、Singularダッシュボードでのデータの正確性を検証してください

アプリ内収益のトラッキング

アプリ内購入（IAP）、サブスクリプション、およびカスタム収益ソースからの収益をトラッキングして、キャンペーンのパフォーマンスと広告費用対効果（ROAS）を測定します。

収益データは3つのチャネルを通じて流れます：

インタラクティブレポート： Singularダッシュボードで収益指標を表示します
エクスポートログ： カスタム分析のための詳細なETLデータにアクセスします
リアルタイムポストバック： 収益イベントを外部プラットフォームに送信します

なぜ収益イベントをトラッキングするのか？

豊富な分析： 詳細なトランザクションデータをキャプチャして、Singularレポートを強化します
不正防止： トランザクションレシート（例：Google PlayまたはApple App Storeから）を含めて購入を検証し、アプリ内の不正に対抗します
キャンペーン最適化： 収益をマーケティング施策に結び付けることでROIを測定します

ベストプラクティス：購入オブジェクト全体を渡す

Androidの（Google Play Billing）またはiOSの（StoreKit）アプリ内購入（IAP）プロセスから返される購入オブジェクトを渡すことを強く推奨します。これにより、Singularは以下を含む包括的なトランザクションの詳細を受け取ります：

製品ID
価格
通貨
トランザクションID
レシートデータ（検証用）

購入オブジェクト全体を渡すことで、より豊富なレポートが可能になり、特にGoogle PlayトランザクションにおいてSingularの不正検出機能を活用できます。

アプリ内購入の統合

IAP購入オブジェクトのキャプチャ

Flutterのin_app_purchaseパッケージを使用して、完全なトランザクションの詳細を含む購入オブジェクトを取得します。

Flutter： iOS StoreKitとAndroid Google Play Billingの両方の購入詳細にアクセスするには、 in_app_purchase パッケージを使用します

InAppPurchaseメソッド

収益の検証と不正防止のために、購入の詳細を含むアプリ内購入イベントをトラッキングします。

メソッドシグネチャ：

static void inAppPurchase(String eventName, SingularIAP purchase)

static void inAppPurchaseWithAttributes(String eventName, SingularIAP purchase, Map attributes)

メソッドの完全な一覧については、 inAppPurchaseメソッドリファレンスを参照してください。

IAP実装の完全な例

IAPイベントをキャプチャし、プラットフォーム固有の購入オブジェクトとともにSingularへ送信する完全な購入リスナーを実装します。

import 'dart:io' show Platform;
import 'package:in_app_purchase/in_app_purchase.dart';
import 'package:in_app_purchase_android/in_app_purchase_android.dart';
import 'package:in_app_purchase_storekit/in_app_purchase_storekit.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_iap.dart';

Future<void> handlePurchase(PurchaseDetails purchaseDetails) async {
  if (purchaseDetails.status != PurchaseStatus.purchased &&
      purchaseDetails.status != PurchaseStatus.restored) {
    return;
  }

  final response = await InAppPurchase.instance
      .queryProductDetails({purchaseDetails.productID});
  if (response.productDetails.isEmpty) {
    return;
  }
  final product = response.productDetails.first;

  // Extract price and currency with platform-specific handling
  double price = 0.0;
  String currency = 'USD';

  if (Platform.isAndroid && product is GooglePlayProductDetails) {
    final offer = product.productDetails.oneTimePurchaseOfferDetails;
    price = (offer?.priceAmountMicros ?? 0) / 1000000;
    currency = offer?.priceCurrencyCode ?? 'USD';
  } else if (Platform.isIOS && product is AppStoreProductDetails) {
    price = product.skProduct.price;
    currency = product.skProduct.priceLocale.currencyCode ?? 'USD';
  }

  SingularIAP? singularPurchase;

  if (Platform.isAndroid && purchaseDetails is GooglePlayPurchaseDetails) {
    singularPurchase = SingularAndroidIAP(
      price,
      currency,
      purchaseDetails.billingClientPurchase.signature,
      purchaseDetails.billingClientPurchase.originalJson,
    );
  } else if (Platform.isIOS && purchaseDetails is AppStorePurchaseDetails) {
    singularPurchase = SingularIOSIAP(
      price,
      currency,
      purchaseDetails.productID,
      purchaseDetails.skPaymentTransaction.transactionIdentifier ?? '',
      purchaseDetails.verificationData.serverVerificationData,
    );
  } else {
    return;
  }

  const String eventName = 'iap_purchase';

  // Track with attributes (use only ONE tracking method)
  Singular.inAppPurchaseWithAttributes(eventName, singularPurchase, {
    'user_level': 42,
    'is_first_purchase': true,
    'gems_balance': 1500
  });

  await InAppPurchase.instance.completePurchase(purchaseDetails);
}

手動の収益トラッキング

購入検証なしの収益

Purchaseオブジェクトを使用せず、通貨、金額、およびオプションの製品詳細を渡して収益をトラッキングします。この方法では検証用のトランザクションレシートが提供されない点にご注意ください。

重要： 有効な購入オブジェクトなしで収益イベントを送信する場合、Singularはトランザクションを検証しません。可能な限り、上記で説明した inAppPurchase() メソッドを使用することを強く推奨します。

注：通貨は3文字のISO 4217通貨コードとして渡してください。例： USD 、 EUR 、 INR 。

CustomRevenueメソッド

指定したイベント名、通貨、金額を使用して、カスタム収益イベントをトラッキングします。

import 'package:singular_flutter_sdk/singular.dart';

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

メソッドシグネチャ：

static void customRevenue(String eventName, String currency, double amount)

メソッドの完全な一覧については、 customRevenueメソッドリファレンスを参照してください。

CustomRevenueWithAttributesメソッド

指定したイベント名、通貨、金額、および追加のカスタム属性を使用して、カスタム収益イベントをトラッキングします。

import 'package:singular_flutter_sdk/singular.dart';

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

メソッドシグネチャ：

static void customRevenueWithAttributes(
  String eventName,
  String currency,
  double amount,
  Map attributes
)

メソッドの完全な一覧については、 customRevenueWithAttributesメソッドリファレンスを参照してください。

CustomRevenueWithAllAttributesメソッド

製品SKU、名前、カテゴリ、数量、およびカスタム属性を含む、すべての可能な属性を使用してカスタム収益イベントをトラッキングします。

import 'package:singular_flutter_sdk/singular.dart';

// Track custom revenue with all attributes
Singular.customRevenueWithAllAttributes(
  'CoinPackagePurchase',
  'USD',
  4.99,
  'coin_package_abc123',
  'Coin Pack 10',
  'Virtual Currency',
  2,
  {
    'payment_method': 'google_play',
    'transaction_id': 'T12345'
  }
);

メソッドシグネチャ：

static void customRevenueWithAllAttributes(
  String eventName,
  String currency,
  double amount,
  String productSKU,
  String productName,
  String productCategory,
  int productQuantity,
  Map attributes
)

メソッドの完全な一覧については、 customRevenueWithAllAttributesメソッドリファレンスを参照してください。

サブスクリプション収益

サブスクリプションのトラッキング

Singularは、Singular SDKを使用したサブスクリプションイベントの実装に関する包括的なガイドを提供しています。このガイドでは、さまざまなプラットフォームにわたるアプリ内サブスクリプションイベントのトラッキングを扱っています。

サブスクリプション収益をトラッキングしたい場合は、サブスクリプションイベント技術実装ガイドをお読みください

ハイブリッドイベントトラッキング（上級）

CDPおよびサードパーティ統合との非互換性： SDIDは、CDP（Segment、mParticle）やサードパーティのサブスクリプションプロバイダー（RevenueCat、Adapty）と互換性がありません。SDIDが有効になっている場合、これらのプラットフォームをイベント転送のために並行して使用することはできず、不完全または破損したアトリビューションにつながります。

Singularは、最適なアトリビューションのために、アプリに統合されたSingular SDKを通じてすべてのイベントと収益を送信することを推奨しています。ただし、必要に応じて、Singularは他のソースからイベントを収集できます。

Singular SDK以外で送信されるイベントは、Singularの Server-to-Serverイベントドキュメントの要件に準拠し、正しいアトリビューションのために一致するデバイス識別子を提供する必要があります。

重要：

Server-to-Serverイベントリクエストで使用されるデバイス識別子が、Singular内の一致するデバイス識別子を持たない場合、不一致が発生します。以下の可能性に注意してください：

早期イベント： Singular SDKがApp Sessionからデバイス識別子を記録する前にイベントリクエストが受信された場合、そのイベントリクエストは未知のデバイスの「最初のセッション」とみなされ、Singularはそのデバイスを オーガニックアトリビューション として帰属させます
不一致の識別子： Singular SDKがデバイス識別子を記録したものの、それがServer-to-Serverイベントリクエストで指定されたデバイス識別子と異なる場合、そのイベントは 誤って帰属されます

ハイブリッドイベントトラッキングガイド

内部サーバーからのイベント送信

内部サーバーから収益データを収集して、キャンペーンのパフォーマンスとROIを分析します。

要件：

デバイス識別子のキャプチャ： アプリ内の登録またはログインイベントから、デバイス識別子をキャプチャして渡し、このデータをユーザーIDとともにサーバーに保存します。デバイス識別子はユーザーごとに変わる可能性があるため、ユーザーがアプリセッションを生成したときに識別子を更新してください。これにより、サーバーサイドのイベントが正しいデバイスに帰属されることが保証されます
プラットフォーム固有の識別子： サーバーサイドのイベントはプラットフォーム固有であり、デバイスプラットフォームに一致するデバイス識別子とともにのみ送信する必要があります（例：iOSデバイスの場合はIDFAまたはIDFV、Androidデバイスの場合はGAID）
リアルタイム更新： Singular Internal BIポストバックメカニズムを使用して、イベントをリアルタイムで内部エンドポイントにプッシュし、サーバーサイドでデータセットを更新できるようにします。 Internal BIポストバックFAQ を参照してください
実装の詳細： 詳細については、Server-to-Server統合ガイドの収益のトラッキングセクションを確認してください

収益プロバイダーからのイベント送信

RevenueCatやadaptyなどのサードパーティ収益プロバイダーを統合して、購入およびサブスクリプション収益をSingularに送信します。

サポートされているプロバイダー：

RevenueCat： 詳細は RevenueCatドキュメントをご覧ください
adapty： 詳細は adaptyドキュメントをご覧ください
Superwall： 詳細は Superwallドキュメントをご覧ください
Xsolla： 詳細は Xsollaドキュメントをご覧ください

Segmentからのイベント送信

Segmentに「Cloud-Mode」宛先を追加することで、SegmentがSingular SDKと並行してSingularにイベントを送信できるようにします。

詳細なセットアップ手順については、実装ガイド Singular-Segment統合に従ってください。

Flutter SDK - アプリ内イベントのトラッキング

アプリ内イベントのトラッキング

標準イベントと属性

イベントタイプの理解

カスタムイベントの制限

イベントの送信

Eventメソッド

EventWithArgsメソッド

ベストプラクティス

アプリ内収益のトラッキング

なぜ収益イベントをトラッキングするのか？

アプリ内購入の統合

IAP購入オブジェクトのキャプチャ

InAppPurchaseメソッド

IAP実装の完全な例

手動の収益トラッキング

購入検証なしの収益

CustomRevenueメソッド

CustomRevenueWithAttributesメソッド

CustomRevenueWithAllAttributesメソッド

サブスクリプション収益

サブスクリプションのトラッキング

ハイブリッドイベントトラッキング（上級）

ハイブリッドイベントトラッキングガイド

内部サーバーからのイベント送信

収益プロバイダーからのイベント送信

Segmentからのイベント送信