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

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

標準イベントと属性

標準イベントの使用

Singularは、レポートと最適化のために広告ネットワークが認識する標準イベントをサポートします。自動認識と簡素化されたセットアップのために、可能な限り標準イベント名を使用してください。

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

各イベントはさまざまな属性をサポートします。実装の詳細は、イベントごとの推奨される標準属性を参照してください。

イベントの送信

イベント実装のガイドライン

ユーザーのアクションや行動をトラッキングするには、 event または eventWithArgs メソッドを使用してSingularにイベントを送信します。

標準イベント: 標準イベントリストのイベントのiOS名を使用します。例: EVENT_SNG_LOGIN
カスタムイベント: 標準イベントと一致しないアプリ固有のイベントの場合は、文字数制限を遵守する任意の説明的な文字列を使用してください

カスタムイベントの制限事項:

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

event メソッド

追加情報なしで、シンプルなトラッキングシナリオでユーザーイベントを報告します。

メソッドシグネチャ:

+ (void)event:(NSString *)name;

+event: は void を返します — 呼び出し時点では成功/失敗のシグナルはありません。名前が nil または空の場合、あるいは +start: がまだ呼び出されていない場合、SDKはイベントを黙ってドロップします。問題はログを確認してください。

使用例

// Example 1: Standard event
Singular.event(EVENT_SNG_LOGIN)

// Example 2: Custom event
Singular.event("signup")

// Example 1: Standard event
[Singular event:EVENT_SNG_LOGIN];

// Example 2: Custom event
[Singular event:@"signup"];

eventWithArgs メソッド

構造化データのために、辞書形式で追加情報とともにユーザーイベントを報告します。

メソッドシグネチャ:

+ (void)event:(NSString *)name withArgs:(NSDictionary *)args;

注意: args パラメータは、1つ以上のキーと値のペアを含むNSDictionaryです。キーは文字列でなければならず、値はNSDictionaryで許可される任意の型を使用できます。

使用例

// Example 1: Standard event with recommended attributes
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_CONTENT_TYPE] = "video"
dic[ATTRIBUTE_SNG_ATTR_CONTENT_ID] = "32"
dic[ATTRIBUTE_SNG_ATTR_CONTENT] = "Telugu"
dic[ATTRIBUTE_SNG_ATTR_SUCCESS] = "yes"

Singular.event(EVENT_SNG_TUTORIAL_COMPLETE, withArgs: dic)

// Example 2: Custom event with custom attributes
var bonusData: [AnyHashable: Any] = [
    "level": 10,
    "points": 500
]
Singular.event("Bonus Points Earned", withArgs: bonusData)

// Example 1: Standard event with recommended attributes
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"video" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_TYPE];
[dic setValue:@"32" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_ID];
[dic setValue:@"Telugu" forKey:ATTRIBUTE_SNG_ATTR_CONTENT];
[dic setValue:@"yes" forKey:ATTRIBUTE_SNG_ATTR_SUCCESS];

[Singular event:EVENT_SNG_TUTORIAL_COMPLETE withArgs:dic];

// Example 2: Custom event with custom attributes
NSMutableDictionary *bonusData = [[NSMutableDictionary alloc] init];
[bonusData setValue:@10 forKey:@"level"];
[bonusData setValue:@500 forKey:@"points"];

[Singular event:@"Bonus Points Earned" withArgs:bonusData];

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

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

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

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

収益イベントの制限事項:

イベント名: カスタム収益イベント名は ASCII 32文字に制限されます(非ASCIIはUTF-8変換時に32バイト)
属性: イベント属性名と値はASCII 500文字に制限されます
通貨コード: すべて大文字で、3文字の ISO 4217標準に従う必要があります(例:USD、EUR、INR)

ベストプラクティス

標準命名: Singularの標準イベントと属性の命名規則を使用してください
言語: 広告ネットワークのポストバック互換性を高めるため、カスタム収益イベント名は英語で送信してください
ゼロ以外の金額: 金額が0より大きいか小さい場合にのみ収益イベントを送信してください

非サブスクリプションのアプリ内購入

SKPaymentTransaction連携

StoreKitの SKPaymentTransaction オブジェクトを iapComplete メソッドに渡し、リッチなレポートとトランザクション検証を実現します。

メリット:

リッチデータ: Singularは包括的なレポートのために完全なトランザクションの詳細を受け取ります
不正防止: トランザクションのレシートにより、アプリ内不正対策の検証が可能になります

注意:

必須オブジェクト: iapComplete メソッドには SKPaymentTransaction オブジェクトが必要です
通貨変換: 異なる通貨の収益は、組織が指定した通貨に自動的に変換されます
カスタムイベント名: レポートでイベントタイプ別に収益を分類するには、 withName パラメータを使用してください

iapComplete メソッド

自動検証と豊富なデータのために、SKPaymentTransactionオブジェクトとともに収益イベントを送信します。

メソッドシグネチャ:

+ (void)iapComplete:(id)transaction;
+ (void)iapComplete:(id)transaction withName:(NSString *)name;

使用例

// Get the SKPaymentTransaction object
let transaction: SKPaymentTransaction = ...

// Send transaction without custom event name
Singular.iapComplete(transaction)

// Send transaction with custom event name
Singular.iapComplete(transaction, withName: "MyCustomRevenue")

// Get the SKPaymentTransaction object
SKPaymentTransaction *transaction = ...;

// Send transaction without custom event name
[Singular iapComplete:transaction];

// Send transaction with custom event name
[Singular iapComplete:transaction withName:@"MyCustomRevenue"];

サブスクリプション収益

サブスクリプションイベントの実装

サブスクリプションの購入と更新をトラッキングして、ユーザー行動と継続的な収益発生に関するインサイトを得ます。

実装ガイド: Singular SDKでサブスクリプションをトラッキングする詳細な手順は、包括的なサブスクリプションイベント技術実装ガイドを参照してください。

購入検証なしのカスタム収益

手動収益トラッキング

SKPaymentTransactionオブジェクトを使用せずに、通貨、金額、オプションの製品の詳細を渡して収益をトラッキングします。このメソッドでは、検証用のトランザクションレシートは提供されません。

重要: これらのメソッドを使用する場合、Singularはトランザクションを検証できません。可能な場合は、上記で説明したSKPaymentTransactionメソッドの使用を強く推奨します。

revenue メソッド

通貨、金額、オプションの製品の詳細とともに収益イベントを送信します。

メソッドシグネチャ:

+ (void)revenue:(NSString *)currency amount:(double)amount;

+ (void)revenue:(NSString *)currency
         amount:(double)amount
     productSKU:(NSString *)productSKU
    productName:(NSString *)productName
productCategory:(NSString *)productCategory
productQuantity:(int)productQuantity
   productPrice:(double)productPrice;

+ (void)revenue:(NSString *)currency
         amount:(double)amount
 withAttributes:(NSDictionary *)attributes;

使用例

// Without product details
Singular.revenue("USD", amount: 1.99)

// With product details
Singular.revenue("EUR",
    amount: 5.00,
    productSKU: "SKU1928375",
    productName: "Reservation Fee",
    productCategory: "Fee",
    productQuantity: 1,
    productPrice: 5.00)

// With product details in a dictionary
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"

Singular.revenue("USD", amount: 19.95, withAttributes: dic)

// Without product details
[Singular revenue:@"USD" amount:1.99];

// With product details
[Singular revenue:@"EUR"
           amount:5.00
       productSKU:@"SKU1928375"
      productName:@"Reservation Fee"
  productCategory:@"Fee"
  productQuantity:1
     productPrice:5.00];

// With product details in a dictionary
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt"
       forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];

[Singular revenue:@"USD" amount:19.99 withAttributes:dic];

customRevenue メソッド

指定したイベント名、通貨、金額、およびオプションのトランザクション属性とともにカスタム収益イベントを送信します。

メソッドシグネチャ:

+ (void)customRevenue:(NSString *)eventName
             currency:(NSString *)currency
               amount:(double)amount;

+ (void)customRevenue:(NSString *)eventName
             currency:(NSString *)currency
               amount:(double)amount
           productSKU:(NSString *)productSKU
          productName:(NSString *)productName
      productCategory:(NSString *)productCategory
      productQuantity:(int)productQuantity
         productPrice:(double)productPrice;

+ (void)customRevenue:(NSString *)eventName
             currency:(NSString *)currency
               amount:(double)amount
       withAttributes:(NSDictionary *)attributes;

使用例

// Without product details
Singular.customRevenue("MyCustomRevenue", currency: "USD", amount: 1.99)

// With product details
Singular.customRevenue("MyCustomRevenue",
    currency: "EUR",
    amount: 5.00,
    productSKU: "SKU1928375",
    productName: "Reservation Fee",
    productCategory: "Fee",
    productQuantity: 1,
    productPrice: 5.00)

// With product details in a dictionary
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"

Singular.customRevenue("CustomRevenueWithArgsDic",
    currency: "USD",
    amount: 44.99,
    withAttributes: dic)

// Without product details
[Singular customRevenue:@"MyCustomRevenue" currency:@"USD" amount:1.99];

// With product details
[Singular customRevenue:@"MyCustomRevenue"
               currency:@"EUR"
                 amount:5.00
             productSKU:@"SKU1928375"
            productName:@"Reservation Fee"
        productCategory:@"Fee"
        productQuantity:1
           productPrice:5.00];

// With product details in a dictionary
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt"
       forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];

[Singular customRevenue:@"MyCustomRevenue"
               currency:@"USD"
                 amount:44.99
         withAttributes:dic];

StoreKit2サポート

StoreKit2収益トラッキング

StoreKit2フレームワークを使用するアプリでは、トランザクションと製品のJSON表現とともに customRevenue メソッドを使用してください。

重要: StoreKit2では購入検証はサポートされていません。これらのメソッドではトランザクションと製品オブジェクトに jsonRepresentation 形式が必要です。

メソッドシグネチャ:

+ (void)customRevenue:(NSData *)transactionJsonRepresentation
productJsonRepresentation:(NSData *)productJsonRepresentation;

+ (void)customRevenue:(NSString *)eventName
transactionJsonRepresentation:(NSData *)transactionJsonRepresentation
productJsonRepresentation:(NSData *)productJsonRepresentation;

使用例

// Fetch transaction and product from StoreKit2
let transaction = ... // Valid StoreKit2 transaction
let product = ... // Valid StoreKit2 product

// Custom Revenue with default __iap__ event name
Singular.customRevenue(
    transactionJsonRepresentation: transaction.jsonRepresentation,
    productJsonRepresentation: product.jsonRepresentation)

// Custom Revenue with custom event name
Singular.customRevenue(
    "PaymentSuccess",
    transactionJsonRepresentation: transaction.jsonRepresentation,
    productJsonRepresentation: product.jsonRepresentation)

// Fetch transaction and product from StoreKit2
SKTransaction *transaction = ...;  // Valid StoreKit2 transaction
SKProduct *product = ...;          // Valid StoreKit2 product

// Convert JSON representations to NSData
NSData *transactionData = [transaction.jsonRepresentation
    dataUsingEncoding:NSUTF8StringEncoding];
NSData *productData = [product.jsonRepresentation
    dataUsingEncoding:NSUTF8StringEncoding];

// Custom Revenue with default __iap__ event name
[Singular customRevenue:transactionData
    productJsonRepresentation:productData];

// Custom Revenue with custom event name
[Singular customRevenue:@"PaymentSuccess"
    transactionJsonRepresentation:transactionData
    productJsonRepresentation:productData];

ハイブリッドイベントトラッキング(上級)

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

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

重要:

サーバー間リクエストのデバイス識別子がSingular SDKが記録した識別子と一致しない場合、不一致が発生します:

早期イベント: Singular SDKがデバイス識別子を記録する前にイベントが到着すると、そのイベントは未知のデバイスの「最初のセッション」となり、オーガニックアトリビューションになります
不一致の識別子: Singular SDKがサーバー間リクエストとは異なるデバイス識別子を記録した場合、そのイベントは誤ってアトリビューションされます

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

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

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

要件:

デバイス識別子のキャプチャ: アプリ内の登録またはログインイベント時にデバイス識別子をキャプチャして渡し、このデータをUser IDとともにサーバーに保存します。正しいアトリビューションのために、ユーザーが新しいアプリセッションを開始したときに識別子を更新してください
プラットフォーム固有の識別子: プラットフォームに対応するデバイス識別子(例:iOSデバイスの場合はIDFAまたはIDFV)を用いてサーバー側のイベントを送信してください
リアルタイム更新: Singular Internal BIポストバック機構を使用して、エンドポイントにイベントをリアルタイムでプッシュしてください。 Internal BI Postback FAQ を参照してください
実装の詳細: サーバー間連携ガイドの「Tracking Revenue」セクションを参照してください

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

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

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

RevenueCat: 詳細は RevenueCatのドキュメントを参照してください
adapty: 詳細は adaptyのドキュメントを参照してください

Segmentからのイベント送信

Segmentに「Cloud-Mode」のデスティネーションを追加することで、Singular SDKと並行してSegmentからSingularへイベントを送信できるようにします。

詳細な設定手順は、実装ガイド Singular-Segment連携 を参照してください。

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

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

標準イベントと属性

標準イベントの使用

イベントの送信

イベント実装のガイドライン

event メソッド

使用例

eventWithArgs メソッド

使用例

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

ベストプラクティス

非サブスクリプションのアプリ内購入

SKPaymentTransaction連携

iapComplete メソッド

使用例

サブスクリプション収益

サブスクリプションイベントの実装

購入検証なしのカスタム収益

手動収益トラッキング

revenue メソッド

使用例

customRevenue メソッド

使用例

StoreKit2サポート

StoreKit2収益トラッキング

使用例

ハイブリッドイベントトラッキング(上級)

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

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

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

Segmentからのイベント送信