Quick Tracking:埋め込み API

1. トラッキングソリューションの表示方法

ポイントを埋め込む前に、どこにポイントを埋め込むか、どのポイントを埋め込むかを決定する必要があります。つまり、ポイントを埋め込むための明確な要件を整理する必要があります。QuickTracking プラットフォームでは、トラッキングポイントの明確な要件をトラッキングポイントスキームと呼び、トラッキングポイントスキーム用の仕様テンプレートが設計されています。次のとおりです。

埋設点スキームでは、必要な埋設点は以下のとおりです。

1. イベントの主体：イベントをトリガーした「人物」。イベントはデバイス ID とアカウント ID に分けることができます。イベントには、これらのいずれかが必要です。

• デバイス ID：Android デバイスと iOS デバイスのデフォルトのデバイス ID は、アプリレベルの一意のデバイス ID であり、Quicktracking によって自動的に生成されます。

  • Android 9 以降のデバイスでは、SDK は imei、wifimac、androidid、およびシリアル番号を自動的に収集してデバイス ID を生成します。デバイス ID が生成されると、ローカルに保存されます。デバイス ID は、アプリケーションがアンインストールされるか、アプリケーションデータが削除された後にのみ再生成されます。

  • Android 10 以上のデバイス：SDK は OAID、GAID、Android ID、シリアル番号を自動的に収集してデバイス ID を生成します。デバイス ID が生成されると、デバイス ID はローカルに保存されます。デバイス ID が再度生成されるのは、アプリケーションがアンインストールされた後、またはアプリケーションデータが削除された後のみです。

  • iOS デバイス：SDK は OpenUDID を自動的に収集してデバイス ID を生成します。デバイス ID が生成されると、キーチェーンに配置されます。デバイス ID が再度生成されるのは、工場出荷時の設定に復元された後、またはアプリケーションデータが削除された後のみです。

  • Quick Tracking SDK が IDFA および OAID を収集するのは、アプリケーションのエンドユーザーがその収集に同意した場合に限られます。QuickTracking アプリ SDK のみが OAID、GAID、IMEI、Wi-Fi MAC アドレス、Android ID、SN、IDFV を収集できます。

• アカウント ID：ログイン後のクライアントユーザーのアカウント ID。ユーザーが異なるデバイスからログインすると、デバイス ID は変更されますが、アカウント ID は変更されません。たとえば、ユーザーが携帯電話とパッドを使用して個別にログインする場合などです。

2. ユーザー属性：アカウント ID の属性。たとえば、アカウント ID が「testdemo@111」、誕生日が「1999-02-13」、メンバーレベルが「プラチナ」などのユーザー。「誕生日」と「メンバーシップ」の評価はユーザー属性です。

3. チャネル属性：広告配信の属性。たとえば、配信チャネル、配信方法、配信コンテンツなど。

4. グローバル属性：一度グローバル設定した後に各イベントによって伝達される属性

5. ページ閲覧イベント：ページ読み込み中にレポートされるイベント (トラッキングスキームでページコードとイベントコードが等しいイベントも青でマークされたイベントです)。

6. クリック、露出、カスタムイベント：クライアントユーザーがクライアントと対話したときに報告されるイベント

2. デバイス ID とアカウント ID を設定する

2.1 デバイス ID の設定

SDK は、デフォルトで次のパラメーターを収集します。

開発者が上記の表にある特定のデバイス識別子の収集を制御したい場合、たとえば、開発者がデバイス識別子を収集しない、または収集メソッドを自分で実装する場合などです。次の例に示すように、対応するブロックコールバックを実装できます。

[QTConfigure customSetIdfaBlock:^NSString *{
  return @""; // idfa を設定しない
}];
[QTConfigure customSetIdfvBlock:^NSString *{
  return @""; // idfv を設定しない
}];
[QTConfigure customSetOpenUdidBlock:^NSString *{
  return @"custom-openudid"; // カスタム openudid を設定する
}];
[QTConfigure customSetUtdidBlock:^NSString *{
  return @"custom-utdid"; // カスタム utdid を設定する
}];
[QTConfigure customSetMccBlock:^NSString *{
  return @"custom-mcc"; // カスタム mcc を設定する
}];
[QTConfigure customSetMncBlock:^NSString *{
  return @"custom-mnc"; // カスタム mnc を設定する
}];

注：対応するメソッドを実装するかどうかは慎重に判断してください。メソッドを実装することを選択した場合、デバイス識別子の収集は開発者の責任となります。SDK はデバイス識別子の収集を試みません。SDK が収集できるデバイス識別子が少ないほど、統計データの精度と安定性に悪影響が及びます。

// 収集ドメイン名を設定し、SDK の事前初期化関数を呼び出す前に、収集ツールクラスの登録関数を呼び出します。
// デバイス ID の収集動作を制御する必要がない場合は、カスタムユーティリティクラスを実装して登録する必要はありません。
[QTConfigure customSetIdfvBlock:^NSString *{
    return [[UIDevice currentDevice].identifierForVendor UUIDString];
}];
[QTConfigure setCustomDomain:@"ご利用の受信ドメイン名" standbyDomain:nil];
[QTConfigure initWithAppKey:@"ご利用の AppKey" channel:@"App Store"]; 

SDK はカスタムデバイス ID をサポートしています。カスタムデバイス ID を使用する場合は、初期化前（つまり、init 前）に setCustomDeviceId を有効な値（空でない）に設定する必要があります。

+ (void)setCustomDeviceId:(NSString *)devID;

使用例：

[QTConfigure setCustomDeviceId:@"xxxxxx"];

注：この関数は、デバイス ID が取得されない場合に有効になります。ローカルデバイスにデバイス ID がすでに存在する場合、設定は無効です。デバイス ID がローカルで取得されている場合は、デバイスをアンインストールして再インストールできます。

2.2 アカウント ID の設定

1. QT はユーザーをカウントする際にデバイスを基準とします。アプリケーション自体のアカウントをカウントする必要がある場合は、次のインターフェイスを使用してください。

インターフェイス関数：

+ (void)profileSignInWithPUID:(NSString *)puid;

パラメーター：

注：アカウント ID は設定後、ローカル記憶域に保存されます。アカウント ID は、アプリがアンインストールされた場合、アプリケーションデータがクリアされた場合、または次のログアウトインターフェイスが呼び出された場合にのみ無効になります。それ以外の場合、各イベントはアカウント ID を伝達します。

サンプルコード：

[QTMobClick profileSignInWithPUID:@"UserID"];

ユーザーアカウントのバインドが不要になった場合は、ログアウトインターフェイスを呼び出すことができます。ログアウトインターフェイスを呼び出すと、アカウント関連のコンテンツは送信されなくなります。

+ (void)profileSignOff;

サンプルコード：

[QTMobClick profileSignOff];

2.3 デバイス ID の取得

インターフェイス関数：

+ (NSString *)umidString;

サンプルコード：

NSString *deviceID = [QTConfigure umidString];

3 ユーザー属性のアップロード

1. イベントコードが「$$_user_profile」に固定されているカスタムイベントをアップロードします。イベントによって伝達されるイベント属性は、ユーザー属性としてユーザーテーブルに配置されます。

NSDictionary *dict = @{@"sex" : @"girl", @"age" : @"8"};
[QTMobClick event:@"$$_user_profile" attributes:dict];

注：ユーザー属性は、アカウント統計呼び出しの後にアップロードする必要があります

4 チャネル属性

チャネル属性が有効になると、後続のすべてのイベントにこれらの属性が自動的に含まれ、これらの属性と属性値はキャッシュに保存され、APP プロセスが終了した後にクリアされます。データを分析するときに、このプロパティに基づいて表示およびフィルタリングできます。

4.1 H5 リンクによるアプリの起動

1. アプリの URL スキームにこれらのチャネル属性を含めます。属性キーは、SDK が認識するキーワードであるため、「utm_」で始まる必要があります。例：<URL scheme>? utm_channel=gzh

2. プロジェクトに URL スキームを追加します。URL スキームは、プロジェクト設定の [target] -> [Info] タブ -> [URL Types] にあります。入力されたスキーム。AppDelegate で関数 [MobClick handleUrl:url] を呼び出して URL を受信します。

AppDelegate の呼び出し：

- (BOOL)application:(UIApplication *)application openURL:(nonnull NSURL *)url options:(nonnull NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
 if ([QTMobClick handleUrl:url]) {
 return YES;
 }

 return YES;
}

SceneDelegate の呼び出し：

- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {

 for (UIOpenURLContext *context in connectionOptions.URLContexts) {
 [QTMobClick handleUrl:context.URL];
 }
}

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {

 [QTMobClick handleUrl:URLContexts.allObjects.firstObject.URL];
}

PS：市場のチャネル配信会社と協力していて、utm_ で始めることができない場合は、グローバル属性 API を使用してチャネル属性を報告できます。属性キーは utm_ で始まる必要があります。

4.2 H5 リンクでアプリケーションマーケットを呼び出し、アプリケーションをダウンロードして起動

このシナリオでは、H5 URL に utm_ パラメーターのみが含まれている場合、アプリのダウンロード後に utm_ パラメーターを起動イベントに含めることができません。したがって、「H5 起動イベント」と「アプリケーション起動イベント」の間で「IP アドレスとブラウザー UserAgent」に関してあいまい一致を実行する必要があります。

1. ユーザーが H5 の「アプリを呼び出す/ダウンロード」ボタンをクリックすると、「アプリ呼び出しイベント（$$_app_link）」が報告されます。イベントには、呼び出しアプリの appkey とチャネル属性を含める必要があります。

// 例
aplus_queue.push({
  action:'aplus.recordAppLink',
  arguments:[{
    targetAppKey: 'Application appKey', // 必須。起動するアプリケーションの appKey。
    custom1: 'custom1', // オプション。カスタムパラメーター。
    ...
  }]
})

2. アプリのアクティベーションイベント ($$_app_install) は、QT App SDK によって自動的に収集およびレポートされます。

3. QuickTracking システムは、IP アドレスとブラウザー UserAgentに関して、アプリケーション起動イベント（$$_app_link）とアプリケーション起動イベント（$$_app_install）の間であいまい一致を実行します。使用するときは、アプリアプリケーションの「アプリケーション起動（プリセット）」のチャネルプロパティを直接分析できます。

4.3 アプリマーケットのアクティブデータ統計

初期化関数の 2 番目の入力パラメーターは、アプリケーションのマーケットプレイスです：[QTConfigure initWithAppkey:@"ご利用の AppKey" channel:@"App Store"];。システムプロパティセクションで更新チャネルを表示できます。

5 グローバル属性

グローバル属性が登録されると、後続のすべてのイベントにこれらの属性が自動的に含まれます。これらの属性と属性値はメモリに保存され、APP プロセスの終了後にクリアされます。データを分析する際に、このプロパティに基づいて表示およびフィルタリングできます。

5.1 グローバル属性を登録する

/**
 * グローバルプロパティのキーと値のペアを設定します。
 * 既存のグローバルプロパティに同じキーが存在する場合、値は上書き更新されます。
 * 存在しない場合は、新しいグローバルプロパティとして追加されます。
 */
+(void) registerGlobalProperty:(NSDictionary *)property;

例：

NSDictionary *firstPropertyDict = @{
     @"a" : @"1",
     @"b" : @"2"
};
[QTMobClick registerGlobalProperty:firstPropertyDict];// 現在の globalproperty は a:1 と b:2
    
NSDictionary *secondPropertyDict = @{
     @"b" : @"3",
     @"c" : @"4"
};
[QTMobClick registerGlobalProperty:secondPropertyDict];// 現在の globalproperty は a:1、b:3、c:4

5.2 グローバルプロパティを取得する

/**
 * グローバルプロパティを取得します。存在しない場合は空を返します。
 */
+(NSString *) getGlobalProperty:(NSString *)propertyName;

5.3 グローバル属性を削除する

特定のグローバルプロパティを削除します。プロパティが削除されると、トリガーされる後続のすべてのイベントは、そのプロパティを伝達しなくなります。

/**
 *
 * 指定されたグローバル属性を削除します。
 @param key
 */
+(void) unregisterGlobalProperty:(NSString *)propertyName;

5.4 すべてのグローバルプロパティを取得する

/**
 * すべてのグローバルプロパティを取得します。存在しない場合は空を返します。
 */
+(NSDictionary *)getGlobalProperties;

5.5 すべてのグローバル属性をクリアする

/**
 * すべてのグローバル属性をクリアします。
 */
+(void)clearGlobalProperties;

6 ページ閲覧イベント API

SDK は、ページ閲覧イベントをレポートするために、ページの自動収集とページの手動収集の 2 つのメソッドを提供します。2 つのメソッドは併用することもできます。

6.1 ページの自動収集

ページの自動収集は、システムの viewWillAppear と viewWillDisappear をフックし、className を取得することで実装されます。デフォルトでは、SDK のページの自動収集は無効になっています。これを有効にする場合は、初期化の前にこの操作を呼び出すことを推奨します。

インターフェイス関数：

+ (void)setAutoPageEnabled:(BOOL)value;

サンプルコード：

// ページの自動収集を有効にします。
[QTMobClick setAutoPageEnabled:YES];

6.1.1 単一ページの自動レポートを無効にする

ページの自動収集をグローバルに有効にした場合、この操作を呼び出してページの自動収集をスキップできます。この操作は、viewWillAppear 操作の開始時に呼び出すことを推奨します。現在のページの自動収集を統計しない場合は、pageName パラメーターを nil に設定できます。

インターフェイス関数：

+ (void)skipMe:(id)PageObject pageName:(NSString *)pageName;

例：

#import <QTCommon/UMSpmHybrid.h>

- (void)viewWillAppear:(BOOL)animated
{
  
    [super viewWillAppear:animated];

    // 現在のクラスのページの自動収集はカウントされません。
    [UMSpmHybrid skipMe:[self class] pageName:nil];
}

6.2 ページの手動収集

インターフェイス関数：

/**ページの表示時間を記録するための自動ページ滞在時間統計。
 使用法：自動統計を完了するには、beginLogPageView: と endLogPageView: の 2 つの関数を呼び出す必要があります。1 つの関数しか呼び出されない場合、有効なデータは生成されません。
 ページが表示されたときに beginLogPageView: を呼び出し、ページを終了するときに endLogPageView を呼び出します：
 @ param pageName 統計が収集されるページの名前。
 @return void。
 */
+ (void)beginLogPageView:(NSString *)pageName;

/**ページの表示時間を記録するための自動ページ滞在時間統計。
 使用法：自動統計を完了するには、beginLogPageView: と endLogPageView: の 2 つの関数を呼び出す必要があります。1 つの関数しか呼び出されない場合、有効なデータは生成されません。
 ページが表示されたときに beginLogPageView: を呼び出し、ページを終了するときに endLogPageView を呼び出します：
 @ param pageName 統計が収集されるページの名前。
 @return void。
 */
+ (void)endLogPageView:(NSString *)pageName;

パラメーター：

注：

• beginLogPageView: 関数と endLogPageView: 関数の 2 つの関数をペアで呼び出して、自動統計を完了する必要があります。1 つの関数のみが呼び出された場合、有効なデータは生成されません。

• ページが表示されたら beginLogPageView を呼び出し、ページが閉じられたら endLogPageView を呼び出します。

サンプルコード：

ViewController クラスで、viewWillAppear: および viewWillDisappear: で、以下のメソッドをペアで呼び出します。

- (void)viewWillAppear:(BOOL)animated
{
 [super viewWillAppear:animated];
 [QTMobClick beginLogPageView:@"Pagename"]; //("Pagename" はページ名で、カスタマイズできます)
}

- (void)viewWillDisappear:(BOOL)animated 
{
 [super viewWillDisappear:animated];
 [QTMobClick endLogPageView:@"Pagename"];
}

また、ビジネスシナリオに応じて、viewDidAppear: メソッドと viewDidDisappear: メソッドで beginLogPageView: 関数と endLogPageView: 関数を呼び出し、自動統計を実装することもできます。

6.2.1 ページプロパティ設定

iOS ページプロパティ設定インターフェース updatePageProperties を使用すると、現在のページにカスタムプロパティをアタッチできます。 インターフェース：

/**
 * @brief ページのビジネス パラメーターを更新します。
 *
 * @param pageName ページの名前。例: Page_Detail
 * @param pProperties ビジネス パラメーター。キーと値のペアです。
 *
 * @warning 呼び出しの説明: viewWillDisappear の前に呼び出す必要があります。
 *
 * 最適な場所: viewWillDisappear の前に呼び出す
 */
+(void) updatePageProperties:(NSString *)pageName properties:(NSDictionary *) pProperties;

パラメーター：

注: ページプロパティを設定した後に beginLogPageView を呼び出してください。

ヘッダーファイルの紹介:

#import <QTCommon/UMSpm.h>

例：

[UMSpm updatePageProperties:@"page_home" properties: @{@"page_home_key":@"page_home_val"}]; // UMSpm updatePageProperties:@"page_home"、properties: @{@"page_home_key":@"page_home_val"} を設定します

注: ページに対して設定できるのは手動トラッキングのみです。

6.2.2 ページプロパティのパススルー

さらに、Quick Tracking SDK は、パススルーページプロパティトラッキングインターフェイス updateNextPageProperties も提供します。これにより、次のページにカスタムプロパティをアタッチできます。

/**
 * @brief 次のページのビジネス パラメーターを更新します。
 *
 * @param properties ビジネス パラメーターを次のページに渡します。 KV ペア
 *
 * @warning 呼び出しの説明：呼び出しは、次のページの pageAppear の前に実行する必要があります。 そうしないと、エラーが発生します。
 *
 * 最適な場所：次のページの pageAppear の前に呼び出す必要があります
 */
+(void) updateNextPageProperties:(NSDictionary *) properties;

パラメーター：

例：

次のページの beginLogPageView の前に呼び出す必要があります。

[UMSpm updateNextPageProperties:@{@"news_next_key":@"news_next_val"}]; // 次ページのプロパティを更新

注: ページ属性には手動トラッキングのみ使用できます。

7. イベントの埋め込みポイント

カスタムイベントを使用して、ユーザーの行動を追跡し、行動発生の具体的な詳細を記録できます。

7.1 イベントトラッキングポイント

インターフェース：

+ (void)event:(NSString *)eventCode; // イベントコード

+ (void)event:(NSString *)eventCode attributes:(NSDictionary *)attributes; // イベントコード、属性

+ (void)event:(NSString *)eventId pageName:(NSString *)pageName attributes:(NSDictionary *)attributes; // イベントID、ページ名、属性

パラメーターの説明：

イベントアップロード数量制限：

• カスタムプロパティキー文字列の最大長：1024

• カスタム属性値文字列の最大長：1024 * 4

• カスタム属性マップの長さ（パラメーターの数）：100 キーバリューペア

• カスタムプロパティ値が配列要素の場合、プロパティ値の最大配列長は 100 です。

• 単一のログメッセージの全長は 2MB に制限されています。

例 1：

アプリケーションで発生した "forward" イベントの回数をカウントし、転送関数を呼び出します。

[QTMobClick event:@"Forward"]; // 転送イベントを記録

例 2：

アプリケーションで「購入」イベントが発生した回数と、購入された商品の種類と数量をカウントし、購入関数で呼び出します。

NSDictionary *dict = @{@"type" : @"book", @"quantity" : @"3"}; // 購入商品の種類と数量
[QTMobClick event:@"purchase" attributes:dict]; // 購入イベントと属性を記録

例 3:

NSDictionary *dict = @{@"type" : @"book", @"quantity" : @"3"}; // 購入商品の種類と数量
[QTMobClick event:@"purchase" pageName:@"ViewController" attributes:dict]; // 購入イベント、ページ名、属性を記録

8 フル埋め込みポイント (自動埋め込みポイント)

8.1 フル埋込ポイントの適用範囲

SDK は iOS 8.0 以降に対応しています。

8.2 全埋点インターフェースの説明

8.2.1 ページの自動収集インターフェイス

/**データを自動的に収集するかどうかを設定します。デフォルト値は NO です。
 @ param value が YES に設定されている場合、QT SDK はページ情報を自動的に収集します
 */
+ (void)setAutoPageEnabled:(BOOL)value;

例：

 [QTMobClick setAutoPageEnabled:YES];
 // ドメイン名を設定します。
 [QTConfigure setCustomDomain:@"Your receipt domain name" standbyDomain:nil]; 
 // アプリケーションキーを初期化します。
 [QTConfigure initWithAppkey:@"AppKey of your application" channel:@"App Store"]; 

ページの自動ページ収集を無効にする

/**
 * @brief 現在のページの統計情報をスキップします。
 *
 * @param PageObject コンテナーのオブジェクト。このパラメーターは、ページを自動的に取得するために使用されます。デフォルトでは、このパラメーターは nil に設定できます。
 * @param pageName ページの名前。このパラメーターは、ページを手動で構成する場合に使用されます。自動ページ取得を構成する場合は、nil を入力できます。
 * @warning ページを設定する前に、この操作を呼び出すことをお勧めします。この操作を呼び出した後、ネイティブページはデータを送信しません。
 *                          
 */
+ (void)skipMe:(id)PageObject pageName:(NSString *)pageName;

例：

[UMSpmHybrid skipMe:self pageName:nil];

8.2.2 コントロールを開き、データトラッキングポイントをクリックする

デフォルトでは閉じられているため、初期化の前に呼び出すことを推奨します。

/**クリックイベントを自動的に収集するかどうかを設定します。デフォルト値は NO です。
 @ param value が YES に設定されている場合、QT SDK はクリックイベントを自動的に収集します
 */
+ (void)setAutoEventEnabled:(BOOL)value;

例:

 [QTMobClick setAutoEventEnabled:YES];
 // ドメイン名を設定します。
 [QTConfigure setCustomDomain:@"Your receipt domain name" standbyDomain:nil]; 
 // アプリケーションキーを初期化します。
 [QTConfigure initWithAppkey:@"AppKey of your application" channel:@"App Store"]; 

サポートされているコントロール:

コンテナーのクリックイベントを無視する

/**
 * @abstract
 * ページ上のクリックを無視します。
 *
 * @param PageObject コンテナー。
 */
+(void)ignorePageView:(id)PageObject;

例:

// このメソッドは複数の呼び出しをサポートし、コレクションを無視します。
[QTAutoTrack ignorePageView:self];

特定の種類のコントロールのクリックイベントの自動収集を無視する

ignoreViewType メソッドを使用して、特定の種類のコントロールのクリックイベントの自動収集を無視します。

/**
 * @abstract
 * 特定の種類のクリックを無視します。
 *
 * @param aClass 対応するクラスを表示します。
 */
+(void)ignoreViewType:(Class)aclass;

例：

// このメソッドは複数の呼び出しをサポートし、コレクションを無視します。
[QTAutoTrack ignoreViewType:[UIButton class]];    
[QTAutoTrack ignoreViewType:[UISwitch class]];

特定のコントロールのクリックイベントの自動収集を無視する

UMAnalyticsIgnoreView メソッドによって、特定のコントロールのクリックイベントの自動収集が無視されます。

button.UMAnalyticsIgnoreView=YES;

8.2.3 ページ設定カスタム情報

ページ設定のカスタムエンコーディング

-(NSString *)getUMPageName メソッドを実装することにより、カスタム エンコーディングが返されます

-(NSString *)getUMPageName
{
   return @"testPageCode";
}

カスタムプロパティ

-(NSDictionary *)getUMPageProperties メソッドを実装することで、ページにカスタムプロパティを設定します

-(NSDictionary *)getUMPageProperties
{
   // key1 と key2 を持つ辞書を返す
   return @{@"key1":@"val1",@"key2":@"val2"};
}

ページ設定ソース ( page_referrer ) 情報

-(NSString *) getUMScreenUrl メソッドを使用して、カスタムソースに関する情報を返すことができます。

- (NSString *)getUMScreenUrl {
    // UMスクリーン URL を取得します。
    return @"um//um/page";
}

8.2.4 コントロールクリックイベントのカスタムプロパティの設定

このメソッドを使用すると、特定のコントロールにカスタムプロパティを設定できます。 カスタムプロパティには、複数のキーと値のペアを設定できます。 キーと値はどちらも文字列型である必要があります。 カスタムプロパティと値は、このコントロールのフルクリックイベントデータに含まれています。

button.UMAnalyticsViewProperties=@{@"key11":@"val11"};

コントロールのイベントコードの設定

このメソッドを使用すると、特定のコントロールのイベントエンコーディングを設定できます。

button.UMAnalyticsEventCode=@"abcd123";