iOS SDK API

SDK インターフェースの説明

1. MTMAService：SDK のすべての API を含みます。
2. MTMAConfig：アプリの設定情報クラス。
3. MTMAInitResult：SDK の初期化結果クラス。
4. MTMAUserID：ユーザー識別子モデル。
5. MTMAUserContact：ユーザーの連絡先モデル。
6. MTMACollectControl：データ収集制御モデル。

MA 機能の起動

対応バージョン

サポート開始バージョン：5.0.0

email、phone 識別子のサポート開始バージョン：5.5.0

単独での初期化のサポート開始バージョン：5.5.0

API 定義

• + (void)start:(MTMAConfig * )config;
  • API の説明：
    • EngageLab MA 機能を有効にします。
    • start は他の API を使用するための開始 API です。他の API を呼び出す前に、必ず start を呼び出してください。
    • スタンドアロン版では MA AppKey の設定が必須です。初期化は AppPush の登録結果に依存しません。
    • 同じアプリプロセス内で、アプリを再起動せずに初期化を繰り返したり、MA AppKey を切り替えたりできます。有効な呼び出しはそれぞれ個別に実行されてコールバックが返され、統合されることはありません。
    • start: と identifyAccount: は呼び出し順に実行されます。前の呼び出しとそのコールバックが終了してから、次の呼び出しを実行します。キューで待機中に元の設定オブジェクトを変更しても、受け付け済みの初期化パラメータには影響しません。
    • MA AppKey の切り替えは、その初期化の実行開始時に反映されます。キューで待機中は、現在のプロジェクトやユーザー識別情報は変わりません。
    • 初期化のたびにネットワーク経由でユーザー識別情報を確認します。今回のコールバックで返される EUID を使用してください。デバイスがオフラインの場合は、接続が回復してから処理を再開し、後続の呼び出しは順番に待機します。失敗時の結果はエラーコードを参照してください。
  • パラメータの説明
    • config：設定クラス

呼び出し例

              
                  MTMAConfig *config = [[MTMAConfig alloc] init];
    config.appKey = @"ご自身の MA AppKey";
    config.resultCompletion = ^(MTMAInitResult *result) {
        if (result.isSuccess) {
            NSLog(@"MTMA の初期化に成功しました");
        } else {
            NSLog(@"MTMA の初期化に失敗しました。code=%ld、message=%@", (long)result.code, result.message);
        }
    };
    [MTMAService start:config];

            

ユーザーの連絡先の設定

対応バージョン

サポート開始バージョン：5.0.0

API 定義

• + (void)setUserContact:(MTMAUserContact * )contact;
  • API の説明：
    • ユーザーの連絡先を設定します。
  • パラメータの説明
    • contacts：複数の連絡先を設定します。現在は email、mobile_phone、landline_phone、whatsapp_phone をサポートしています。Key は長さ 1～256 の文字列、value も文字列である必要があります。"" はその連絡先のクリアを意味します。空ではなく空白のみで構成された文字列は無効です。

呼び出し例

              
                  MTMAUserContact *contact = [[MTMAUserContact alloc] init];
    contact.contacts = @{@"mobile_phone":@"13*********"};
    contact.completion = ^(NSInteger code, NSString * _Nonnull message) { };
    [MTMAService setUserContact:contact];

            

イベントの送信

対応バージョン

サポート開始バージョン：5.0.0

API 定義

• **+ (void)eventRecord:(MTMAEventObject )event;*
  • API の説明：
    • イベントを送信します。
  • パラメータの説明
    • 送信するイベントのモデル
    • eventName：送信するイベントの名前
    • property：イベント属性。Key は属性名、value は属性値です。

呼び出し例

              
                  MTMAEventObject *object = [[MTMAEventObject alloc] init];
    object.eventName = @"sndefineevent2";
    object.property = @{
        @"key1":@"value1",
        @"key2":@"value2",
    };
    [MTMAService eventRecord:object];

            

ユーザー識別子の設定

対応バージョン

サポート開始バージョン：5.0.0

email、phone 識別子のサポート開始バージョン：5.5.0

API 定義

• + (void)identifyAccount:(MTMAUserID * )userID;
  • API の説明：
    • ユーザー識別子を設定します。
  • パラメータの説明
    • ユーザー識別子モデル
    • userID：ログインしたユーザーの一意の識別子を設定します。
    • anonymousID：ユーザーが未ログインでも、識別に使用できる他の情報を提供している場合に、匿名 ID として設定できます。例：メールアドレス、サードパーティが生成した識別 ID。
    • email：ユーザーの識別に使用するメールアドレス。
    • phone：ユーザーの携帯電話番号。+8613800000000 のように国または地域コードを含めてください。
    • 有効な識別子を少なくとも 1 つ指定してください。すべての入力は不要です。詳細は本ドキュメントのユーザー識別子の型、長さ、形式を参照してください。

呼び出し例

              
                  MTMAUserID *userid = [[MTMAUserID alloc] init];
    userid.userID = @"member_10001";
    userid.anonymousID = @"anonymous_10001";
    userid.email = @"member_10001@example.com";
    userid.phone = @"+8613800000000";
    userid.completion = ^(NSInteger code, NSString *message) {
        NSLog(@"result：%ld - %@", code, message);
    };
    [MTMAService identifyAccount:userid];

            

ここでの email、phone はユーザーの識別情報の照合に使用され、新しい EUID が返される場合があります。setUserContact: で設定する連絡先とは相互に代替できません。

コールバックの code=0 は有効な EUID を取得したことを意味し、すべての識別子の設定成功を意味しません。message の JSON にはローカルとサーバーの項目別の結果が含まれ、key は user_id、anonymous_id、email、phone です。対応するフィールドの code で結果を判断してください。フィールドがないことは成功を意味しません。

サーバーが項目別の結果を返さない場合、message にはローカルで拒否された結果のみが含まれます。ローカルでの拒否がなければ success になります。失敗時の message が JSON である保証はありません。項目別のエラーコードについては、ユーザー識別子ごとの処理結果を参照してください。

例：

              
              code=0
message={"email":{"code":0},"phone":{"code":3003,"msg":"ユーザー識別子の値が長さの上限を超えています"}}

            

チャネル連絡先 ID の設定

対応バージョン

サポート開始バージョン：5.5.0

API 定義

• **+ (void)setChannelValueWithChannelId:(NSInteger)channelId values:(NSArray<NSString *> )values completion:(void (^)(NSInteger code, NSString message))completion;
  • API の説明：
    • サードパーティ Push チャネルの RID または Token を設定します。
    • EngageLab AppPush のチャネルの紐付けは SDK が自動的に処理するため、この API で設定する必要はありません。
    • AppPush を統合していない場合や AppPush の登録に失敗した場合も、MA の他の機能には影響しません。
    • 連続して呼び出した場合、SDK は呼び出し順にリクエストを実行し、それぞれの結果をコールバックで返します。
    • キューで待機中に MA AppKey、プロジェクト、ユーザー識別情報が変更された場合、該当するリクエストは -2 を返します。
  • パラメータの説明
    • channelId：MA コンソールのサードパーティ Push チャネル ID。0 より大きい値を指定してください。
    • values：現在のチャネルの RID または Token の配列。SDK は各値の前後の空白を除去してから送信します。配列と、前後の空白除去後の各要素を空にすることはできません。
    • completion：リクエスト結果のコールバック。code が 0 の場合は成功です。

呼び出し例

              
                  [MTMAService setChannelValueWithChannelId:136
                                       values:@[@"サードパーティ Push の RID または Token"]
                                   completion:^(NSInteger code, NSString *message) {
    }];

            

データ送信間隔の設定

対応バージョン

サポート開始バージョン：5.0.0

API 定義

• + (void)setReportInterval:(NSInteger)interval;
  • API の説明：
    • データの送信間隔を設定します。この API を呼び出さない場合、デフォルトでは 10 秒ごとにイベントデータを送信します。
    • 送信間隔はメモリ内に保持されます。設定を有効にするには、アプリのライフサイクルごとに呼び出す必要があります。
  • パラメータの説明
    • interval：送信間隔。単位は s（秒）です。

呼び出し例

              
                  [MTMAService setReportInterval:10];

            

イベントキャッシュ件数の上限設定

対応バージョン

サポート開始バージョン：5.0.0

API 定義

• + (void)setMaxEventCacheCount:(NSInteger)count;
  • API の説明：
    • イベントのキャッシュ件数の上限を設定します。デフォルトは 50 件、最大は 500 件です。
    • キャッシュ件数の上限を超えると、すべてのデータを送信します。
  • パラメータの説明
    • count：イベントのキャッシュ件数の上限

呼び出し例

              
                  [MTMAService setMaxEventCacheCount:50];

            

セッションタイムアウト時間の設定

対応バージョン

サポート開始バージョン：5.0.0

API 定義

• + (void)setNoActiveSessionEndDurationTime:(NSInteger)interval;
  • API の説明：
    • セッションのタイムアウト時間を設定します。デフォルトは 30 分です。
    • アプリがバックグラウンドに移ると、セッションのタイムアウトの計測を開始します。タイムアウト時間内にアクティビティがなければ、現在のセッションを終了します。
  • パラメータの説明
    • interval：タイムアウト時間。単位は s（秒）です。

呼び出し例

              
                  [MTMAService setNoActiveSessionEndDurationTime:50];

            

EUID の取得

対応バージョン

サポート開始バージョン：5.0.0

API 定義

• + (nullable NSString * )EUID;
  • API の説明：
    • EngageLab MA の EUID を取得します。
    • SDK の初期化が成功していない場合は nil を返します。

呼び出し例

              
                  [MTMAService EUID];

            

UTM 属性の設定

対応バージョン

サポート開始バージョン：5.0.0

API 定義

• + (void)setUtmProperties:(NSDictionary * )property;
  • API の説明：
    • UTM 属性は標準のイベント属性です。ユーザーがどの広告からアプリに遷移したかを識別できる場合は、UTM 情報の設定を推奨します。このパラメータはイベント送信時に渡されます。現在設定できる UTM 属性は以下のとおりです：
      • utm_source：キャンペーンの参照元
      • utm_medium：キャンペーンのメディア
      • utm_term：キャンペーンのキーワード
      • utm_content：キャンペーンのコンテンツ
      • utm_campaign：キャンペーン名
      • utm_id：キャンペーン ID

呼び出し例

              
                  [MTMAService setUtmProperties:@{@"utm_source":@"value"}];

            

ユーザー属性の設定

ユーザー属性の上書き更新

• + (void)setProperty:(NSDictionary * )userinfo completion:(void (^)(NSInteger code, NSString * message))completion;
  • API の説明：
    • ユーザー属性を一括で設定します。1 回あたり最大 100 個です。いずれかの属性が SDK の検証に失敗すると、リクエスト全体が送信されません。
    • 属性名は NSString で、小文字の英字で始まり、小文字の英字、数字、アンダースコアのみを含む必要があります。上限は 50 UTF-8 バイトで、el、engagelab、metaverse で始めることはできません。
    • Value は NSString、有限値の NSNumber、文字列の NSSet/NSArray、NSDictionary（object）、NSArray<NSDictionary *>（object_array）をサポートします。
    • 通常の型では、存在する属性は上書きし、存在しない属性は作成します。object はサブフィールドをマージし、object_array は配列の順序を維持して全体を置き換えます。
  • 呼び出し例：

              
                 [MTMAService setProperty:@{
       @"level": @"gold",
       @"profile": @{ @"city": @"Singapore", @"score": @100 },
       @"addresses": @[
           @{ @"id": @"home", @"city": @"Singapore" },
           @{ @"id": @"office", @"city": @"Tokyo" }
       ]
   } completion:^(NSInteger code, NSString * _Nonnull message) {
       // code == 0 はサーバーでの処理成功を示します
   }];

            

• + (void)setProperty:(NSString * )key to:(id)value completion:(void (^)(NSInteger code, NSString * message))completion;
  • API の説明：
    • 単一のユーザー属性の内容を設定します。
    • 属性名、Value の型、更新動作は一括設定 API と同じです。
  • 呼び出し例：

              
                 [MTMAService setProperty:@"profile"
                         to:@{ @"city": @"Singapore", @"score": @100 }
                 completion:^(NSInteger code, NSString * _Nonnull message) {
   }];

            

object / object_array の規則

• object は空ではない NSDictionary である必要があります。サブフィールド名は空ではない NSString で、. または $ を含めることはできません。
• object のサブフィールド値は、NSString、有限値の NSNumber、文字列の NSSet/NSArray、NSNull をサポートします。object または object_array をさらにネストすることはできません。
• object に対して再度 setProperty を呼び出すと、今回渡したサブフィールドのみをマージします。未指定のサブフィールドは変更されません。サブフィールド値に NSNull を渡すと、そのサブフィールドを削除します。
• object_array は NSArray<NSDictionary *> である必要があります。各オブジェクトは空ではなく、同じサブフィールドの規則に従う必要があります。再度 setProperty を呼び出すと、配列全体が置き換わります。
• object_array の各要素には、NSNull ではないサブフィールドが少なくとも 1 つ必要です。すべてのサブフィールド値が NSNull のオブジェクトを渡すことはできません。
• 空の配列は既存の配列属性をクリアするために使用できます。ただし、初回作成時は空の配列だけでは文字列リストと object_array を区別できません。object_array を初めて作成する場合は、1 つ以上のオブジェクトを含む配列を渡してください。
• NSNull は object/object_array のサブフィールド値としてのみ使用できます。トップレベルの NSNull で属性全体を削除することはできません。属性全体を削除するには、deleteProperty:completion: を呼び出してください。

object の部分更新とサブフィールド削除の例：

              
              // profile.score のみを更新し、profile.city は変更しません
[MTMAService setProperty:@"profile"
                      to:@{ @"score": @200 }
              completion:completion];

// profile.city のみを削除します
[MTMAService setProperty:@"profile"
                      to:@{ @"city": NSNull.null }
              completion:completion];

            

object_array 要素の部分更新

サポート開始バージョン：5.5.0

• **+ (void)updateObjectArrayProperty:(NSString *)key identifierKey:(NSString )identifierKey identifierValue:(id)identifierValue values:(NSDictionary<NSString *, id> )values completion:(void (^)(NSInteger code, NSString * message))completion;
  • API の説明：
    • object_array 内のオブジェクトを一意のサブフィールドで特定し、values のサブフィールドをマージします。
    • identifierKey に対応するサブフィールドはサーバーのメタデータで定義済みであり、型は string または number である必要があります。identifierValue は同じ型の NSString、またはブール値ではない有限値の NSNumber とし、現在の配列内で一致する要素が 1 つだけである必要があります。
    • values は空ではない辞書で、identifierKey を含めることや object/object_array をネストすることはできません。未指定のフィールドは変更しません。値に NSNull を渡すと、そのサブフィールドを削除します。
    • この属性はサーバーのメタデータで object_array として定義済みであり、現在のユーザーがその属性値を持っている必要があります。初回作成時は、setProperty:to: に1 つ以上のオブジェクトを含む配列を渡してください。
    • 属性が未定義、または定義済みでも現在のユーザーがまだ値を持っていない場合、サーバーは code=0 を返しますが、変更は行いません。code=0 はリクエスト処理の成功のみを意味します。実際の変更結果は MA コンソールまたはサーバー側のユーザー属性で確認してください。
    • 配列が存在していても、一致する要素がない、複数の要素が一致する、識別フィールドの型が異なる、またはサブフィールドがメタデータ定義に合致しない場合、サーバーは失敗コードを返し、他の要素の作成や変更は行いません。
  • 呼び出し例：

              
              // id == home のオブジェクトで city を Tokyo に更新し、zip を削除します
[MTMAService updateObjectArrayProperty:@"addresses"
                         identifierKey:@"id"
                       identifierValue:@"home"
                                values:@{
                                    @"city": @"Tokyo",
                                    @"zip": NSNull.null
                                }
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

object_array 要素の追加

サポート開始バージョン：5.5.0

• **+ (void)addObjectArrayProperty:(NSString )key object:(NSDictionary<NSString *, id> )object completion:(void (^)(NSInteger code, NSString * message))completion;
  • API の説明：
    • object_array の末尾にオブジェクト要素を 1 つ追加し、既存の要素には影響しません。配列全体を渡して全体を置き換える setProperty:to: とは動作が異なります。
    • object は空ではない NSDictionary で、NSNull ではないサブフィールドを少なくとも 1 つ含む必要があります。サブフィールドの規則は object と同じで、object/object_array のネストはできません。
    • この属性はサーバーのメタデータで object_array として定義済みである必要があります。未定義の場合、サーバーは code=0 を返しますが、変更は行いません。まず setProperty:to: に1 つ以上のオブジェクトを含む配列を渡して初回作成を行ってください。
    • 属性が定義済みで、現在のユーザーがまだ値を持っていない場合、この API はこの 1 つの要素を持つ配列を作成します。
  • 呼び出し例：

              
              [MTMAService addObjectArrayProperty:@"addresses"
                                object:@{
                                    @"id": @"school",
                                    @"city": @"Osaka"
                                }
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

object_array 要素の削除

サポート開始バージョン：5.5.0

• **+ (void)removeObjectArrayProperty:(NSString )key identifierKey:(NSString )identifierKey identifierValue:(id)identifierValue completion:(void (^)(NSInteger code, NSString * message))completion;
  • API の説明：
    • 一意のサブフィールドで要素を特定し、配列要素全体を削除します。要素内の特定のサブフィールドだけを削除する場合は、updateObjectArrayProperty: でそのサブフィールドに NSNull を渡してください。
    • identifierKey / identifierValue の制約は updateObjectArrayProperty: と同じです。サブフィールドはメタデータで定義済みで、型は string または number とし、現在の配列内で一致する要素が 1 つだけである必要があります。
    • この属性がサーバーで未定義の場合、現在のユーザーが属性値を持っていない場合、または一致する要素がない場合、サーバーはリクエストを無視して code=0 を返します。実際の変更結果は MA コンソールまたはサーバー側のユーザー属性で確認してください。
    • 複数の要素が一致する場合や識別フィールドの型が異なる場合、サーバーは失敗コードを返し、他の要素を誤って削除することはありません。
  • 呼び出し例：

              
              // id == office の住所を削除します
[MTMAService removeObjectArrayProperty:@"addresses"
                         identifierKey:@"id"
                       identifierValue:@"office"
                            completion:^(NSInteger code,
                                         NSString *message) {
}];

            

ユーザー属性の加算更新

• **+ (void)increaseProperty:(NSString )key by:(NSNumber )amount completion:(void (^)(NSInteger code, NSString * message))completion;
  • API の説明：
    • 数値型のユーザー属性に値を加算し、送信されたすべてのデータを累積します。例：累計購入金額。
    • この API は NSNumber 型のユーザー属性にのみ使用できます。それ以外は無視されます。属性が存在しなかった場合は、初期値を 0 として処理します。
  • 呼び出し例：

              
                  [MTMAService increaseProperty:@"key" by:@(2) completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

• **+ (void)increaseProperty:(NSDictionary )userinfo completion:(void (^)(NSInteger code, NSString * message))completion;*
  • API の説明：
    • 複数の数値型のユーザー属性に値を加算し、送信されたすべてのデータを累積します。例：累計購入金額。
    • この API は NSNumber 型のユーザー属性にのみ使用できます。それ以外は無視されます。属性が存在しなかった場合は、初期値を 0 として処理します。
  • 呼び出し例：

              
                  [MTMAService increaseProperty:@{@"key1":@(5),@"key2":@(3)} completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

ユーザー属性への値の追加

• **+ (void)addProperty:(NSString )key by:(NSObject )content completion:(void (^)(NSInteger code, NSString * message))completion
  • API の説明：
    • NSSet または NSArray 型の属性に値を追加します。
    • 前述のとおり、NSSet または NSArray の要素は NSString である必要があり、それ以外は無視されます。追加先のユーザー属性が存在しない場合は、空の NSSet または NSArray を初期化します。
  • 呼び出し例：

              
                  [MTMAService addProperty:@"key" by:@[@"value"] completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

• **+ (void)addProperty:(NSDictionary )userinfo completion:(void (^)(NSInteger, NSString * _Nonnull))completion;*
  • API の説明：
    • 複数の NSSet または NSArray 型の属性に値を追加します。
    • 前述のとおり、NSSet または NSArray の要素は NSString である必要があり、それ以外は無視されます。追加先のユーザー属性が存在しない場合は、空の NSSet または NSArray を初期化します。
  • 呼び出し例：

              
                  [MTMAService addProperty:@{@"key1":@[@"value"],@"key2":@[@"value"]} completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

ユーザー属性からの値の削除

• **+ (void)removeProperty:(NSString * )key by:(NSObject )content completion:(void (^)(NSInteger code, NSString * message))completion;*
  • API の説明：
    • NSSet または NSArray 型の属性から値を削除します。
    • content は NSSet または NSArray 型で、要素は NSString である必要があります。
  • 呼び出し例：

              
                  [MTMAService removeProperty:@"key" by:@[@"value"] completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

ユーザー属性の削除

対応バージョン

サポート開始バージョン：5.0.0

API 定義

• + (void)deleteProperty:(NSString * )key completion:(void (^)(NSInteger code, NSString * message))completion;
  • API の説明：
    • 指定したユーザー属性の内容全体を削除します。通常の型、object、object_array に対応します。
    • 属性が存在しない場合は、そのまま無視されます。

呼び出し例

              
                  [MTMAService deleteProperty:@"key" completion:^(NSInteger code, NSString * _Nonnull message) {

    }];

            

データ収集の制御

対応バージョン

サポート開始バージョン：5.0.0

API 定義

• **+ (void)setCollectControl:(MTMACollectControl )control;*
  • API の説明：
    • MTMACollectControl クラスの各データ項目を収集するかどうかを制御します。

呼び出し例

              
                  MTMACollectControl *collectControl = [[MTMACollectControl alloc] init];
    collectControl.idfa = YES;
    collectControl.idfv = YES;
    collectControl.carrier = YES;
    [MTMAService setCollectControl:collectControl];

            

MTMAConfig クラス

アプリの設定情報クラスです。各プロパティの説明は以下のとおりです：

MTMAInitResult クラス

resultCompletion が返す SDK の初期化結果オブジェクトです。個別に作成したり呼び出したりする必要はありません。各プロパティの説明は以下のとおりです：

MTMAUserID クラス

ユーザー識別子のモデルクラスです。初期化時は MTMAConfig.userID、実行中は identifyAccount: で渡します。

4 つの識別子はすべて任意のフィールドで、前後の空白は一律に除去されます。空値と 0/null/undefined/nan（大文字と小文字を区別しない）は未指定として扱い、照合に使用せず、フィールドごとの結果も生成しません。以下の制約は、この処理後に残った値に適用されます：

NSString 以外の型または不正な形式のフィールドは 3013、長さの上限を超えるフィールドは 3003 として除外し、結果を記録します。他の有効なフィールドは引き続き送信されます。有効なフィールドがない場合、初期化は識別情報未指定として続行します。identifyAccount: は -3 を返し、リクエストを送信しません。SDK は呼び出し元のオブジェクトを変更しません。email はサーバー側で小文字に変換されます。

初期化成功時、userID.completion は code=0 を返し、message は空文字列、またはローカルで拒否したフィールドのみを含む JSON になります。サーバーの項目別の結果は含まれないため、これを根拠にすべての識別子が紐付けられたと判断しないでください。SDK の初期化結果は config.resultCompletion を基準に判断してください。このコールバックには識別子ごとの JSON は含まれません。実行中のコールバックについては、ユーザー識別子の設定を参照してください。

MTMACollectControl クラス

ユーザーデータの収集を制御するモデルクラスです。各プロパティの説明は以下のとおりです：

MTMAUserContact クラス

ユーザーのチャネルモデルクラスです。各プロパティの説明は以下のとおりです。
未設定または nil の場合は変更しません。空文字列 "" を設定すると、その連絡先をクリアします。空ではなく空白のみで構成された文字列は無効です。

MTMAEventObject クラス

カスタムイベントのオブジェクトクラスです。各プロパティの説明は以下のとおりです：