概要

MoEngage iOS SDKは、パーソナライズされたキャンペーンを配信するための安全なフレームワークを提供します。ユーザーIDと認証を内部で処理することで統合を簡素化し、APIシークレットの管理や手動でのHTTPS呼び出しを不要にします。これにより、合理化されたネイティブインターフェイスを通じて、パーソナライズされたキャンペーン情報を直接取得およびトラッキングできます。

前提条件パーソナライズされたエクスペリエンスを取得する前に、アプリケーションのエントリーポイント(iOSでは didFinishLaunchingWithOptions)でSDKの initialize() メソッドを呼び出していることを確認してください。詳細については、SDKの初期化を参照してください。

MoEngage Personalizationの統合

SPM (Swift Package Manager)
CocoaPods

SPMを使用して MoEngagePersonalization をインストールするには、次の手順を実行します。

File > Add Package に移動します。
適切なリポジトリURLを入力します。
- https://github.com/moengage/apple-sdk.git (MoEngage-iOS-SDKバージョン9.23.0以上の場合)
- https://github.com/moengage/MoEngage-iOS-SDK.git (その他のバージョンの場合)
masterブランチまたは目的のバージョンを選択します。
Add Package をクリックします。
MoEngagePersonalizationプロダクトをアプリのターゲットに追加します。

以下のように、Podfileに依存関係を追加してMoEngage Personalizeフレームワークを統合します。

情報 CocoaPodsは非推奨になりつつあります。MoEngageでは、すべての新規統合にSwift Package Managerを使用することを推奨しています。詳細については、こちらを参照してください。

Podfile に以下を追加します。

pod 'MoEngage-iOS-SDK/Personalization'

次に、以下を実行します。

pod repo update
pod install

実装ワークフロー

MoEngageSDKPersonalize シングルトンは、iOS上で動的なパーソナライズされたコンテンツの取得と操作を簡素化するように設計されています。SDKは、ネイティブのSwiftメソッドとObjective-C互換のオーバーロードを提供します。

1. Meta Experienceの取得

特定のペイロードやエクスペリエンスを取得する前に、メタデータの呼び出しを実行する必要があります。この手順により、後続のリクエストを正確に処理するために必要な設定とコンテキストがSDKに提供されます。SDKには、SwiftとObjective-Cの両方に専用のメソッドが用意されています。

public func fetchExperiencesMeta(
        status: [MoEngageExperienceStatus],
        onSuccess: @escaping MoEngageMetaSuccessCallback,
        onFailure: @escaping MoEngagePersonalizeFailureCallback,
        workspaceId: String? = nil
    )

@objc(fetchExperiencesMetaWithStatusRawValues:onSuccess:onFailure:workspaceId:)
    public func fetchExperiencesMetaObjC(
        statusRawValues: [NSNumber],
        onSuccess: @escaping MoEngageMetaSuccessCallback,
        onFailure: @escaping MoEngagePersonalizeFailureCallback,
        workspaceId: String? = nil
    )

onSuccess コールバックは、キャンペーンの実行に必要なすべてのメタデータを含む ExperienceCampaignsMetadata オブジェクトを返します。一方、onFailure コールバックは、リクエストが失敗した具体的な理由を特定するための RequestFailureReasonCode とオプションのメッセージを提供します。目的のエクスペリエンスステータスに基づいてコア設定を初期化するため、常に最初にメタデータの取得を呼び出してください。Swiftの配列には標準メソッドを使用し、Objective-Cコードから生のNSNumber値を渡す場合はObjC版を使用します。

2. パーソナライズされたコンテンツの取得

メタデータを取得したら、実際のパーソナライズされたペイロードを取得できます。コンテキストターゲティングを完全にサポートしながら、単一のエクスペリエンスまたは複数のエクスペリエンスを同時に取得できます。単一のエクスペリエンスを取得する以下のコードスニペットは、SwiftとObjective-Cの両方の実装と互換性があります。

Objective-C

 @objc public func fetchExperience(
        experienceKey: String,
        attributes: [String: String] = [:],
        onSuccess: @escaping MoEngageExperienceSuccessCallback,
        onFailure: @escaping MoEngagePersonalizeFailureCallback,
        workspaceId: String? = nil
    )

複数のエクスペリエンスを取得するには:

public func fetchExperiences(
        experienceKeys: Set<String>,// EXPERIENCE_KEY must be one of the keys returned in the fetchExperiencesMeta call. 
    // Using a key that is not part of the meta call or incorrect key will result in an invalid key error.
        attributes: [String: String] = [:],
        onSuccess: @escaping MoEngageExperienceSuccessCallback,
        onFailure: @escaping MoEngagePersonalizeFailureCallback,
        workspaceId: String? = nil
    )

   // MARK: - Multiple Experiences Fetch    @objc(fetchExperiencesWithKeys:attributes:onSuccess:onFailure:workspaceId:)
    public func fetchExperiencesObjC(
        experienceKeys: [String], // EXPERIENCE_KEY must be one of the keys returned in the fetchExperiencesMeta call. 
    // Using a key that is not part of the meta call or incorrect key will result in an invalid key error.
        attributes: [String: String] = [:],
        onSuccess: @escaping MoEngageExperienceSuccessCallback,
        onFailure: @escaping MoEngagePersonalizeFailureCallback,
        workspaceId: String? = nil
    )

onSuccess コールバックは、キャンペーンの実行に必要なすべてのメタデータを含む ExperienceCampaignsResult オブジェクトを返します。一方、onFailure コールバックは、リクエストが失敗した具体的な理由を特定するための RequestFailureReasonCode とオプションのメッセージを提供します。以下を取得できます。

単一のエクスペリエンス: 単一のexperienceKeyを使用して特定のペイロードを取得します。
一括エクスペリエンス: 複数のペイロードを一度に取得します。Swiftでは、Set<String>を渡します。Objective-Cでは、[String]としてブリッジされたNSArrayを受け取る fetchExperiencesObjC メソッドを使用します。

ユースケース: コンテキストターゲティング: 取得時に属性のディクショナリ(例: [“current_page”: “home”, “cart_value”: “500”])を渡します。これにより、リアルタイムで状態に応じたコンテンツ配信が可能になります(例: カートの金額がしきい値を満たした場合に「送料無料」バナーを表示する)。

3. インプレッションのトラッキング

キャンペーンのパフォーマンスを正確に測定するには、パーソナライズされたコンテンツをUIにレンダリングした後に、ユーザーのインタラクションをトラッキングする必要があります。以下のトラッキングコードスニペットは、SwiftとObjective-Cの両方の実装と互換性があります。

3a. Experienceキャンペーンのインプレッションのトラッキング

Objective-C

 // MARK: - Tracking
    
    /// Tracks impression for an experience.
    @objc public func experienceShown(
        campaign: MoEngageExperienceCampaign, //campaign is a placeholder for the campaign objects returned by the fetchExperiences function. They contain the metadata and payload required by the SDK to attribute impressions and clicks to the correct campaign.
        workspaceId: String? = nil
    )
    
    /// Tracks impressions for multiple experiences.
    @objc public func experiencesShown(
        campaigns: [MoEngageExperienceCampaign],
        workspaceId: String? = nil
    )

UIがコンテンツをレンダリングしたときに、これらのメソッドを使用して「インプレッション」(experienceShown / experiencesShown)を記録できます。

3b. Offeringキャンペーンのインプレッションのトラッキング

Offeringsは、パーソナライズされたコンテンツの独自のサブタイプです。SDKは、Offering固有の属性を受け取る専用のトラッキング関数を提供します。以下のトラッキングコードスニペットは、SwiftとObjective-Cの両方の実装と互換性があります。

Objective-C

 // MARK: - Offering Tracking
  
    /// Tracks impression for an offering within an experience.
    @objc public func offeringShown(
        offeringPayload: [String: Any],
        workspaceId: String? = nil
    )
    
    /// Tracks impressions for multiple offerings.
    @objc public func offeringsShown(
        offeringPayloads: [[String: Any]],
        workspaceId: String? = nil
    )

これらのメソッドは、Offeringのディクショナリ全体(campaign.payload 内の offerings 配列の1要素)をサーバーに送信し、カスタムオファーについて非常に詳細な分析を提供します。

4. クリックのトラッキング

4a. Experienceキャンペーンのクリックのトラッキング

Objective-C

 /// Tracks click for an experience.
    @objc public func experienceClicked(
        campaign: MoEngageExperienceCampaign,
        workspaceId: String? = nil
    )

ユーザーがUI要素を操作したときに、これらのメソッドを使用して「クリック」(experienceClicked)を記録できます。

4b. Offeringキャンペーンのクリックのトラッキング:

Objective-C

  /// Tracks click for an offering.
    @objc public func offeringClicked(
        campaign: MoEngageExperienceCampaign,
        offeringPayload: [String: Any],
        workspaceId: String? = nil
    )

これらのOffering固有の関数は、データがOfferingペイロードの一部である場合にのみ使用できます。その他のすべてのエクスペリエンスデータには、標準のexperience shown/clicked関数を使用してください。

これらのメソッドは、Offeringのディクショナリ全体(campaign.payload 内の offerings 配列の1要素)をサーバーに送信し、カスタムオファーについて非常に詳細な分析を提供します。詳細については、APIドキュメントを参照してください。

FAQ

SDKはUIのレンダリングを処理しますか?

いいえ。SDKは生のJSONペイロードを返します。データの解析とUIコンポーネント(バナーやカルーセルなど)の構築はお客様の責任で行ってください。

SDKは画像や動画をキャッシュしますか?

いいえ。SDKはメディアアセットをダウンロードまたはキャッシュしません。JSONで参照される画像、動画、フォントの処理には、標準的なメディア読み込みライブラリを使用してください。

取得できるエクスペリエンスの数に上限はありますか?

はい。1回の呼び出しで最大25件のエクスペリエンスを取得できます。これを超えた場合、SDKは最近更新された25件のエクスペリエンスを返し、取得されなかったキーを通知します。

デバイスがオフラインで有効なキャッシュがない状態で取得リクエストが行われた場合はどうなりますか?

SDKは、空のペイロードと標準化されたエラーコード(例: NETWORK_ERROR)を返します。すべてのエラーの詳細については、こちらを参照してください。

​概要

​MoEngage Personalizationの統合

​実装ワークフロー

​1. Meta Experienceの取得

​2. パーソナライズされたコンテンツの取得

​3. インプレッションのトラッキング

​3a. Experienceキャンペーンのインプレッションのトラッキング

​3b. Offeringキャンペーンのインプレッションのトラッキング

​4. クリックのトラッキング

​4a. Experienceキャンペーンのクリックのトラッキング

​4b. Offeringキャンペーンのクリックのトラッキング:

​FAQ

概要

MoEngage Personalizationの統合

実装ワークフロー

1. Meta Experienceの取得

2. パーソナライズされたコンテンツの取得

3. インプレッションのトラッキング

3a. Experienceキャンペーンのインプレッションのトラッキング

3b. Offeringキャンペーンのインプレッションのトラッキング

4. クリックのトラッキング

4a. Experienceキャンペーンのクリックのトラッキング

4b. Offeringキャンペーンのクリックのトラッキング:

FAQ