ドキュメント

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

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

標準イベントと属性

標準イベントの使用

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

UA、マーケティング、またはビジネスチームは、組織のマーケティングKPIに基づいてイベントのリストを編集する必要があります。アプリ内イベントをトラッキングする方法」を参照してください：ガイド（How to Track In-App Events:Guide For Singular Attribution Customers）を参照してください。

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

イベントの送信

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

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

標準イベント：標準イベントリストにあるイベントのiOS名（例：EVENT_SNG_LOGIN）を使用します。
カスタムイベント：標準イベントに一致しないアプリ独自のイベントには、文字制限に準拠した任意の説明文字列を使用します。

カスタムイベントの制限

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

イベント・メソッド

単純な追跡シナリオのために、追加情報なしでユーザーイベントを報告する。

メソッドのシグネチャ：

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

使用例

// 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データへのアクセス
リアルタイムポストバック：収益イベントを外部プラットフォームへ送信

収益イベントの制限

イベント名：カスタム収益イベント名は32 ASCII文字（またはUTF-8に変換された非ASCIIの場合は32バイト）に制限されます。
属性：イベント属性名と値は500 ASCII文字に制限されます。
通貨コード：すべて大文字で、3文字のISO 4217標準（例：USD、EUR、INR）に従わなければならない。

ベストプラクティス

標準的なネーミング：Singularの標準的なイベントと属性の命名規則を使用してください。
言語：広告ネットワークのポストバックとの互換性を高めるため、カスタム収益イベント名を英語で送信する。
ゼロ以外の金額：金額が0以上の場合のみ、収益イベントを送信します。

サブスクリプション以外のアプリ内課金

SKPaymentTransactionの統合

StoreKitからiapComplete メソッドにSKPaymentTransactionオブジェクトを渡すことで、充実したレポートとトランザクションの検証が可能になります。

メリット

豊富なデータ：包括的なレポートのためにトランザクションの詳細をすべて受け取ります。
不正防止：トランザクションの受信により、アプリ内詐欺に対抗するための検証が可能になります。

注意事項

必須オブジェクト： 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のServer-to-Server Event documentationに準拠し、正しいアトリビューションのために一致するデバイス識別子を提供する必要があります。

重要です：

サーバー間リクエストのデバイス識別子がSingular SDKによって記録された識別子に一致しない場合、不一致が発生します：

初期イベント：Singular SDK がデバイス識別子を記録する前にイベントが到着した場合、そのイベントは未知のデバイスの「最初のセッション」となり、その結果アトリビューションが不正になります。
識別子の不一致：Singular SDKがサーバー間リクエストのデバイス識別子と異なるデバイス識別子を記録した場合、イベントは正しく帰属されません。

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

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

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

要件

デバイス識別子を取得する：アプリ内登録またはログインイベント中に、デバイス識別子を取得して渡し、このデータをユーザーIDとともにサーバーに保存します。ユーザーが新しいアプリセッションを生成したときに識別子を更新し、正しいアトリビューションを確保します。
プラットフォーム固有の識別子：プラットフォーム（iOSデバイスのIDFAまたはIDFVなど）に一致するデバイス識別子を使用して、サーバーサイドのイベントを送信します。
リアルタイム更新：Singular Internal BIのポストバックメカニズムを使用して、イベントをエンドポイントにリアルタイムでプッシュします。内部BIポストバックのFAQを参照してください。
実装の詳細：サーバー間統合ガイドの「収益の追跡」セクションを参照してください。

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

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

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

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

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

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

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

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

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

標準イベントと属性

標準イベントの使用

イベントの送信

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

イベント・メソッド

使用例

eventWithArgs メソッド

使用例

アプリ内収益の追跡

ベストプラクティス

サブスクリプション以外のアプリ内課金

SKPaymentTransactionの統合

iapCompleteメソッド

使用例

サブスクリプション収益

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

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

手動での収益トラッキング

revenue メソッド

使用例

customRevenue メソッド

使用例

StoreKit2 サポート

StoreKit2 収益トラッキング

使用例

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

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

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

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

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