カスタムイベントの制限

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

カスタムイベントの制限

言語： サードパーティのパートナーや分析ソリューションとの互換性を確保するために、イベント名と属性を英語で渡します。
イベント名： ASCII文字32文字まで。非ASCII文字列は、UTF-8に変換したときに32バイト未満でなければなりません。
属性と値： 500ASCII文字に制限

イベントの送信

イベント・メソッド

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)

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

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 Dashboardのデータの正確性を検証します。

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

アプリ内課金（IAP）、サブスクリプション、カスタム収益ソースからの収益を追跡して、キャンペーンパフォーマンスと広告費用対効果（ROAS）を測定します。

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

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

収益イベントを追跡する理由

豊富な分析： 詳細なトランザクションデータを取得し、Singularレポートを強化
不正防止： トランザクションの領収書（Google PlayやApple App Storeなど）を含めることで、購入を検証し、アプリ内詐欺に対処します。
キャンペーンの最適化： 収益とマーケティング活動を結びつけてROIを測定します。

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

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

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

完全な購入オブジェクトを渡すことで、リッチなレポーティングが可能になり、Singularの不正検出機能（特にGoogle Playのトランザクション）を活用できます。

アプリ内課金の統合

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 オブジェクトなしで渡して収益をトラッキングします。このメソッドは検証用のトランザクションレシートを提供しないことに注意してください。

重要： 有効な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を使ったサブスクリプションイベントの実装に関する包括的なガイドを提供しています。このガイドでは、様々なプラットフォームにおけるアプリ内サブスクリプションイベントのトラッキングをカバーしています。

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

ハイブリッドイベント追跡（上級者向け）

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

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

重要です：

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

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

ハイブリッドイベント追跡ガイド

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

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

要件

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

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

RevenueCatやadaptyのようなサードパーティの収益プロバイダーを統合して、購入や購読の収益をSingularに送信します。

サポートしているプロバイダー

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

セグメントからのイベント送信

Segmentに "Cloud-Mode "送信先を追加することで、Singular SDKと並行してSegmentからSingularへイベントを送信できるようになります。

詳細な設定方法については、実装ガイド Singular-Segment Integrationに従ってください。

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

カスタムイベントの制限

イベントの送信

イベント・メソッド

EventWithArgs メソッド

ベスト・プラクティス

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

収益イベントを追跡する理由

アプリ内課金の統合

IAP購入オブジェクトの取得

InAppPurchaseメソッド

完全なIAP実装例

手動の収益トラッキング

購入検証なしの収益

CustomRevenue メソッド

CustomRevenueWithAttributes メソッド

CustomRevenueWithAllAttributes メソッド

サブスクリプション収益

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

ハイブリッドイベント追跡（上級者向け）

ハイブリッドイベント追跡ガイド

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

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

セグメントからのイベント送信