イベントトラッキングは、アプリ内のユーザー行動をトラッキングするために使用されます。トラッキングした行動に基づいて、後でそれらのユーザーをターゲットに関連性の高い通知を送信できます。プロダクトマネージャーやマーケターがアプリユーザーをセグメント化し、ターゲットを絞ったキャンペーンを作成できるよう、ビジネスに関連するすべてのイベントをトラッキングしてください。たとえば、ユーザーが何を購入しているか、ユーザーがカートに商品を追加したかどうかなどをトラッキングできます。

SDKでは特定のイベントをデフォルトでトラッキングしているため、同じシナリオで新しいイベントをトラッキングするのではなく、デフォルトイベントを使用してください。SDKがトラッキングするデフォルトイベントの一覧はこちらを参照してください。
SDKはMoEngageのFUPポリシーに準拠しています。詳細については、公正利用ポリシーを参照してください。

イベントをトラッキングする方法

すべてのイベントは、イベントの「名前」とイベントの プロパティ/属性 の2つの部分で構成されます。イベントとその属性をトラッキングするには、MoEngageProperties を使用する必要があります。たとえば、次のコードは Successful Purchase イベントをトラッキングします。トラッキングするイベントを説明する属性として、Product NameやBrand Nameなどを含めています。

var eventAttrDict: [String: any Sendable] = [:]
eventAttrDict["ProductName"] = "iPhone XS Max"
eventAttrDict["BrandName"] = "Apple"
eventAttrDict["Items In Stock"] = 109

let eventProperties = MoEngageProperties(withAttributes: eventAttrDict)

eventProperties.addAttribute(87000.00, withName: "price")
eventProperties.addAttribute("Rupees", withName: "currency")
eventProperties.addAttribute(true, withName: "in_stock")
eventProperties.addDateEpochAttribute(1439322197, withName: "Time added to cart")
eventProperties.addDateISOStringAttribute("2020-02-22T12:37:56Z", withName: "Time of checkout")
eventProperties.addDateAttribute(Date(), withName: "Time of purchase")

eventProperties.addLocationAttribute(MoEngageGeoLocation.init(withLatitude: 12.23, andLongitude: 9.23), withName: "Pickup Location")

/// JSON is supported from MoEngage-iOS-SDK v9.17.5
eventProperties.addAttribute(["merchantId": "abcdef","business_model": [ "admin_email": "[email protected]","admin_comment": "payment" ]],withName: "merchant")
eventProperties.addAttribute([["merchantId": "abcdef", "business_model": ["admin_email": "[email protected]", "admin_comment": "first"]], ["merchantId": "ghijk", "business_model": ["admin_email": "[email protected]", "admin_comment": "second"]]], withName: "retries")
      
MoEngageSDKAnalytics.sharedInstance.trackEvent("Successful Purchase", withProperties: eventProperties)

// track event example
NSMutableDictionary* eventAttrDict = [NSMutableDictionary dictionary];
eventAttrDict[@"ProductName"] = @"iPhone XS Max";
eventAttrDict[@"BrandName"] = @"Apple";
eventAttrDict[@"Items In Stock"] = @109;

MoEngageProperties* eventProperties = [[MoEngageProperties alloc] initWithAttributes:eventAttrDict];
[eventProperties addAttribute:@(87000.00) withName:@"price"];
[eventProperties addAttribute:@"Rupees" withName:@"currency"];
[eventProperties addAttribute:[NSNumber numberWithBool:true] withName:@"in_stock"];

[eventProperties addDateEpochAttribute:1439322197 withName:@"Time added to cart"];
[eventProperties addDateISOStringAttribute:@"2020-02-22T12:37:56Z" withName:@"Time of checkout"];
[eventProperties addDateAttribute:[NSDate date] withName:@"Time of purchase"];

MoEngageGeoLocation* pickupLocation = [[MoEngageGeoLocation alloc] initWithLatitude:12.23 andLongitude:9.23];
[eventProperties addLocationAttribute:pickupLocation withName:@"Pickup Location"];
      
/// JSON is supported from MoEngage-iOS-SDK v9.17.5
[eventProperties addAttribute:@{@"merchantId": @"abcdef",@"business_model": @{@"admin_email": @"[email protected]",@"admin_comment": @"payment"}} withName:@"merchant"];
[eventProperties addAttribute:@[@{@"merchantId":@"abcdef",@"business_model":@{@"admin_email":@"[email protected]",@"admin_comment":@"first"}},@{@"merchantId":@"ghijk",@"business_model":@{@"admin_email":@"[email protected]",@"admin_comment":@"second"}}] withName:@"retries"];

[[MoEngageSDKAnalytics sharedInstance] trackEvent:@"Successful Purchase" withProperties:eventProperties];

iOS SDK 11.0.0 以降：

MoEngageProperties(withAttributes:) と addAttribute(_:withName:) は、Any ではなく any Sendable の値を受け取ります。属性ディクショナリは [String: any Sendable] として宣言してください。[String: Any] はコンパイルできません。
trackEvent(_:withProperties:) は Void ではなく型付きのタスクオブジェクト（MoEngageTrackEventTask）を返すため、.onSuccess / .onFailure または非同期の result() メソッドを通じて呼び出しごとの成功または失敗を監視できます。上記のような直接の呼び出しは変更なしでコンパイルされます。

非インタラクティブイベントMoEngage Analyticsのセッション時間の計算に一切影響を与えるべきでないイベントは、非インタラクティブイベントとしてマークする必要があります。詳細については、こちらを参照してください。

属性がない場合は、2番目の引数に nil を渡すだけです。例：

MoEngageSDKAnalytics.sharedInstance.trackEvent("Event Name", withProperties: nil)

[[MoEngageSDKAnalytics sharedInstance] trackEvent:@"Event Name" withProperties:nil];

検証と制限

イベント属性には、DEBUG ビルドとリリースビルドの両方に適用される2つのレイヤーの検証があります。

命名とフォーマットのルール — ビルド構成に関係なく常に適用されます。以下の命名とフォーマットのルールを参照してください。
型の検証 — 無効な属性値（null、カスタムモデル、NaN、Infinity、空のコレクション、ArrayまたはDictionary内にネストされた Date/MoEngageGeoLocation などのサポートされていない型）は、DEBUG ビルドでは致命的な例外を引き起こし、リリースビルドではペイロードから通知なく破棄されます。イベントの残りの部分はトラッキングされます。以下のサポートされている属性値の型を参照してください。

iOS SDKにおける DEBUG モードとは、SDKが initializeDefaultTestInstance(_:)（TESTワークスペース）を使用して初期化され、アプリがXcodeに接続された状態で実行されていることを意味します。これは、デバッグシンボルが有効になっているリリースビルドとは異なります。

命名とフォーマットのルール

属性名は空にできません。 属性名として空の文字列（""）を渡すと、DEBUG ビルドでは致命的な例外が発生します。リリースビルドでは、その属性は破棄されます。
予約済みプレフィックス。 イベント、イベント属性、ユーザー属性の名前に moe_ をプレフィックスとして使用することはできません。これはシステムプレフィックスであり、使用すると事前の連絡なく定期的にブロックリストに登録される場合があります。

サポートされている属性値の型

属性値は、String、Number、Date、MoEngageGeoLocation、Dictionary（文字列キーとサポートされている値を持つもの）、Array（サポートされている値の配列）のいずれかである必要があります。サポートされていない値が渡された場合：

DEBUG ビルドでは、開発の早い段階でデータの問題を明らかにするため、SDKが致命的な例外をスローしてアプリをクラッシュさせます。
ReleaseビルドおよびTestFlightビルドでは、SDKは該当する無効な属性を通知なく破棄し、問題をログに記録します。イベントペイロードの残りの部分は引き続きトラッキングされます。

DEBUG 例外の一般的な原因：

null（NSNull()）を渡す。
カスタムモデルやUI要素（例：UIColor、UIImage）を渡す。
NaN や Infinity などの無効な数値を渡す。
空のArrayまたはDictionaryを渡す。
ArrayまたはDictionary内に Date または MoEngageGeoLocation オブジェクトをネストする。これらは値として直接渡す必要があります。

アップグレード中にこれらの DEBUG 検証によってアプリがクラッシュする場合は、SDKを初期化する前に MoEngageSDKCore.sharedInstance.disableIntegrationValidator() を呼び出して一時的にオプトアウトしてください。問題が修正されたら、この呼び出しを削除してください。

サポートされていない属性値のフィルタリング

新しいバージョンのiOS SDKにアップグレードする際に、呼び出し箇所で型が検証されていない属性値をアプリが渡している場合は、MoEngageProperties オブジェクトを構築する前に型チェックのガードを追加してください。これにより DEBUG でのクラッシュを防ぎ、すべてのビルドで有効なデータのみがSDKに届くようになります。

// Helper to check if a value is a supported event attribute type.
  // Call this before passing any dynamically-typed value to addAttribute(_:withName:).
  // Starting with iOS SDK 11.0.0, addAttribute(_:withName:) requires `any Sendable` instead of `Any`.
  func isSupportedEventAttributeValue(_ value: any Sendable) -> Bool {
      switch value {
      case let d as Double: return !d.isNaN && !d.isInfinite
      case let f as Float:  return !f.isNaN && !f.isInfinite
      case is String, is Bool, is Int, is Int8, is Int16, is Int32, is Int64,
           is UInt, is UInt8, is UInt16, is UInt32, is UInt64, is NSNumber:
          return true
      case let arr as [Any]:        return !arr.isEmpty
      case let dict as [String: Any]: return !dict.isEmpty
      default: return false
      }
  }

  // Usage — value comes from a server response, external model, or unknown source
  let properties = MoEngageProperties()
  if isSupportedEventAttributeValue(dynamicValue) {
      properties.addAttribute(dynamicValue, withName: "attribute_name")
  }

// Check if a value is a supported event attribute type before passing to the SDK.
  - (BOOL)isSupportedEventAttributeValue:(id)value {
      if ([value isKindOfClass:[NSString class]] || [value isKindOfClass:[NSNumber class]]) {
          // Guard against NaN / Infinity for floating-point NSNumbers
          if ([value isKindOfClass:[NSNumber class]]) {
              double d = [(NSNumber *)value doubleValue];
              if (isnan(d) || isinf(d)) return NO;
          }
          return YES;
      }
      if ([value isKindOfClass:[NSArray class]])      return [(NSArray *)value count] > 0;
      if ([value isKindOfClass:[NSDictionary class]]) return [(NSDictionary *)value count] > 0;
      return NO;
  }

  // Usage
  MoEngageProperties *properties = [[MoEngageProperties alloc] init];
  if ([self isSupportedEventAttributeValue:dynamicValue]) {
      [properties addAttribute:dynamicValue withName:@"attribute_name"];
  }

Date と MoEngageGeoLocation の値は、ディクショナリベースの withAttributes: イニシャライザーや addAttribute:withName: ではなく、専用の addDateAttribute、addDateEpochAttribute、addDateISOStringAttribute、addLocationAttribute メソッドを使用して渡す必要があります。

手動同期

トラッキングしたイベントを即座に同期するには、以下のように flush() メソッドを使用します。

MoEngageSDKAnalytics.sharedInstance.flush()

[[MoEngageSDKAnalytics sharedInstance] flush];

統合後のイベントのテスト

アプリ用に提供された認証情報でMoEngageアカウントにログインします。左上を確認し、Test 環境に切り替えます。テストデータをLiveデータと分離しておくため、テストは必ずテスト環境で行ってください。SDKを初期化していることを確認してください。上記のようにアプリにイベントトラッキングを追加した後、Dashboard > Recent Events にアクセスして、イベントがトラッキングされているかどうかを確認できます。 イベントがダッシュボードに表示されるまでに最大20分かかる場合があります テスト中は、デバッグモードでのログを有効にすることをお勧めします。 SDKは現在のフラッシュで同期されたすべてのイベントの一覧を出力するため、トラッキングしたイベントがバックエンドに送信されているかどうかは、いつでもログで確認できます。また、ログにはバックエンドとの同期が成功したかどうかの情報も含まれます（失敗した場合、SDKはトラッキングしたすべてのイベントを保存し、次回のフラッシュ時に再度同期を試みます）。

​イベントをトラッキングする方法

​検証と制限

​命名とフォーマットのルール

​サポートされている属性値の型

​サポートされていない属性値のフィルタリング

​手動同期

​統合後のイベントのテスト

イベントをトラッキングする方法

検証と制限

命名とフォーマットのルール

サポートされている属性値の型

サポートされていない属性値のフィルタリング

手動同期

統合後のイベントのテスト