Quick Tracking:埋め込み API

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

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

埋設点方式では、必要な埋設点は以下のとおりです。

1. イベントの主体：イベントをトリガーした 「誰」 を指します。イベントは デバイス ID と アカウント ID に分けることができ、イベントにはどちらか一方が必須です。

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

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

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

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

  • Quick Tracking SDK は、アプリケーションの C- ターミナルユーザーが IDFA および OAID の収集に同意した場合にのみ、これらを収集します。QuickTracking アプリ SDK のみが OAID、GAID、IMEI、WiFIMAC、AndroIID、SN、IDFV を収集できます。

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

2. ユーザー属性: 例えば、あるユーザーのアカウント ID が "testdemo@111"、誕生日が "1999-02-13"、メンバーレベルが "platinum" である場合などです。「誕生日」や「メンバーシップ」はユーザー属性です。

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

4. グローバル属性：一度グローバル設定された後、各イベントに付与される属性です。

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

6. クリック、露出、カスタムイベント：クライアントユーザーがクライアントと対話する際にレポートされるイベントです。

2. デバイス ID とアカウント ID の設定

2.1 デバイス ID の設定

SDK は、`com.quick.qt.commonsdk` パッケージパスに、デフォルトのデバイス識別子収集ツールクラス `DefaultDeviceInfo` を実装しています。このデフォルトの実装クラスは、デフォルトで以下の識別子を収集します。

開発者が上記の表にある特定のデバイス識別子の収集を制御したい場合、例えば IMEI フィールドと Serial フィールドを収集せず、OAID の収集方法を開発者が実装する場合などです。`DefaultDeviceInfo` クラスのサブクラスを実装し、`getImi`、`getSerial`、`getOaid` の 3 つの収集メソッドをオーバーロードすることができます。次の例を参照してください：

import com.quick.qt.commonsdk.DefaultDeviceInfo;

public class CustomDeviceInfo extends DefaultDeviceInfo {

	@Override
	public String getImei(Context context) {
		return null;
	}

	@Override
	public String getSerial() {
		return null;
	}

	@Override
	public String getOaid(Context context) {
		String oaid = "";
        // oaid = getOaidMethod(); // 独自の oaid 取得メソッド
        return oaid;
	}

}

注意：デバイス識別子を再読み込みしない場合、デバイス識別子は Quick Tracking SDK によってデフォルトで収集されます。対応するメソッドを実装する際は注意が必要です。メソッドを実装することを選択した場合、デバイス識別子の収集はお客様の責任となります。SDK はデバイス識別子の収集を試みません。SDK が収集できるデバイス識別子が少ないほど、統計データの精度と安定性に悪影響が及びます。

カスタムツールクラスの登録：

import com.quick.qt.commonsdk.QtConfigure;

// 収集ドメイン名を設定し、SDK の事前初期化関数を呼び出す前に、収集ツールクラスの登録関数を呼び出します。
// デバイス ID の収集動作を制御する必要がない場合は、カスタムユーティリティクラスを実装して登録する必要はありません。
QtConfigure.setDeviceInfo(new CustomDeviceInfo());
QtConfigure.setCustomDomain("Your collection service domain name", null); 

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

public static void setCustomDeviceId(Context var0, String var1)

使用例：

import com.quick.qt.commonsdk.QtConfigure;

QtConfigure.setCustomDeviceId(this, "xxxxxx");

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

2.2 デバイス ID の取得

以下のメソッドを使用して取得できます：

import com.quick.qt.commonsdk.QtConfigure;

QtConfigure.getUMIDString(this)

2.3 アカウント ID の設定

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

public static void onProfileSignIn(String ID);

注：アカウント ID がセットされると、ローカル記憶域に保存されます。アカウント ID は、アプリケーションがアンインストールされた場合、アプリケーションデータが消去された場合、または次のログインインターフェイスが呼び出された場合にのみ無効になります。それ以外の場合、各イベントにはアカウント ID が付与されます。

2. アカウントからログオフする際には、この操作を呼び出す必要があります。この操作を呼び出した後、アカウント関連のコンテンツは送信されません。

public static void onProfileSignOff();

例：

import com.quick.qt.analytics.QtTrackAgent;

// ユーザーが自分のアカウントでログインすると、以下の統計が収集できます：
QtTrackAgent.onProfileSignIn("userID");

// ログアウト
QtTrackAgent.onProfileSignOff();

import com.quick.qt.analytics.QtTrackAgent;
import java.util.HashMap;
import java.util.Map;

Map<String, Object> user = new HashMap<String, Object>();
user.put("sex", "girl");// 性別
user.put("age", "8"); // 年齢
QtTrackAgent.onEventObject(mContext, "$$_user_profile", user);

4. チャネル属性

4.1 H5 リンクによるアプリの呼び出し

チャネル属性を追跡する必要はありませんが、ミニプログラムまたはアプリの URL にはこれらのチャネル属性が含まれている必要があり、SDK が認識するキーワードは `utm_` であるため、属性キーは `utm_` で始まる必要があります。例：

<URL scheme>?utm_channel=gzh

PS：市場のチャネル配信会社と協力しており、`utm_` で始めることができない場合は、Global Attributes 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 システムは、アプリケーション呼び出しイベント ($$_app_link) とアプリケーション有効化イベント ($$_app_install) の間で、IP アドレスとブラウザの UserAgentに関してあいまい一致を実行します。使用する際には、アプリアプリケーションで「アプリケーション有効化 (プリセット)」のチャネルプロパティを直接分析できます。

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

QtConfigure.preInit(this, "your appkey","Channel-Huawei"); QtConfigure.init(this, "your appkey","Channel-Huawei");

5. グローバル属性

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

5.1 グローバルプロパティの登録

public static void registerGlobalProperties(Context var0, Map<String, Object> var1);

数値の説明：

注意：

1. String 型のプロパティ名とプロパティ値。大文字と小文字のアルファベット、数字、アンダースコアのみがサポートされています！

2. プロパティ値は、次の Java 型のいずれかです：String、Long、Integer、Float、Double、Short。

3. キーが既存のグローバル属性のキーと同じ場合は既存の値が更新され、異なる場合は新しいグローバル属性が挿入されます。

   例：

   import com.quick.qt.analytics.QtTrackAgent;
   import java.util.HashMap;
   import java.util.Map;
   
   Map firstMap = new HashMap<String, Object>();
   firstMap.put("a", "1");
   firstMap.put("b", "2");
   QtTrackAgent.registerGlobalProperties(mContext, firstMap);// 現在の globalproperty は a:1 と b:2 です
   
   Map secondMap = new HashMap<String, Object>();
   secondMap.put("b", "3");
   secondMap.put("c", "4");
   QtTrackAgent.registerGlobalProperties(mContext, secondMap);// 現在の globalproperty は a:1、b:3、c:4 です

5.2 グローバル属性の削除

public static void unregisterGlobalProperty(Context context, String propertyName);

例：

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

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.unregisterGlobalProperty(mContext, "lnch_Source");

5.3 キーに基づいて単一のグローバル属性を取得する

public static Object getGlobalProperty(Context context, String propertyName);

例：

import com.quick.qt.analytics.QtTrackAgent;

String userId = QtTrackAgent.getGlobalProperty(mContext, "lnch_Source");

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

public static String getGlobalProperties(Context context);

例：

import com.quick.qt.analytics.QtTrackAgent;

String allSuperProp = QtTrackAgent.getGlobalProperties(mContext);

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

public static void clearGlobalProperties(Context context);

例：

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.clearGlobalProperties(mContext);

6. ページ閲覧イベント API

6.1 ページのマニュアルコレクション

Activity、Fragment、CustomView、その他のカスタムページのページパスとページ滞在時間に関する統計を収集したい開発者向けです。`QtTrackAgent.onPageStart` または `QtTrackAgent.onPageEnd` 操作を呼び出して、データを手動で追跡できます。

public static void onPageStart(String viewName);
public static void onPageEnd(String viewName);

Fragemnt ページのパスを手動でカウントするコード例：

import com.quick.qt.analytics.QtTrackAgent;

// onPageStart -> onPageEnd の一対の呼び出しは、フラグメントなどの非アクティビティページのライフサイクル統計に対応します。

// Fragment ページの onResume 関数をオーバーライドします。
public void onResume() {
    super.onResume();
    QtTrackAgent.onPageStart("MainScreen"); // 統計ページ ("MainScreen" はページエンコーディングで、カスタマイズ可能です) 
}

// Fragment ページの onPause 関数をオーバーライドします。
public void onPause() {
    super.onPause();
    QtTrackAgent.onPageEnd("MainScreen");
}

注意：

`onPageStart` は SDK がページエントリ情報を記録するために使用されます。`onPageStart` はイベントをレポートしません。PageView イベントは `onPageEnd` が呼び出されたときにのみレポートされます。

`onPageStart` と `onPageEnd` メソッドはペアで呼び出す必要があります。`onPageStart` と `onPageEnd` メソッドの `page_name` は同じでなければなりません。`onPageEnd` が指定されていないか、`onPageEnd` と `onPageStart` メソッドの `page_name` が一致しない場合、`onPageStart` メソッドで記録された情報は有効になりません。

6.1.1 ページプロパティのアップロード

`QtTrackAgent.setPageProperty()` は、現在のページにカスタムプロパティをアタッチすることをサポートします。

インターフェイス：`QtTrackAgent.setPageProperty`

パラメーター：

例：

Activity ページが表示され始めたときに現在のページのプロパティを設定する例：

import com.quick.qt.analytics.QtTrackAgent;

private static final String PAGE_NAME = "page_home"; // ページの名前
 
 @Override
 public void onResume() {
    super.onResume();
   
    QtTrackAgent.onPageStart(PAGE_NAME); // ページの開始点
    Map<String, Object> params = new HashMap<>();
    params.put("home_param_1", "value11"); // 現在のページのプロパティを設定
    QtTrackAgent.setPageProperty(mContext, PAGE_NAME, params);
 }

注意：ページに対して手動追跡のみを設定できます。

6.1.2 ページプロパティの引き渡し

さらに、QuickTracking SDK は `SpmAgent.updateNextPageProperties` インターフェイスを提供しており、これにより次のページにカスタムプロパティをアタッチできます。

インターフェイス：`SpmAgent.updateNextPageProperties`

パラメーター：

サポートされている型：

/**
* 
この関数は、次のタブにジャンプするときに呼び出されます。
*/
public static void updateNextPageProperties(Map<String, Object> params)

値を渡す例：

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.spm.SpmAgent;

public class MainActivity extends AppCompatActivity {
    private static final String PAGE_NAME = "page_home"; // ページの名前
    private Button mGoNewsWithHole;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        setTitle("QuickTracking Statistics Home Page");
        setContentView(R.layout.activity_u4a_home);

        binding.btnGoToDetail.setOnClickListener(v -> {
            // 次のページにカスタムプロパティを追加します。
            Map<String, Object> params = new HashMap<>();
            params.put("my_transfer_arg1", "MainActivity with passthrough property values");
            SpmAgent.updateNextPageProperties(params); //
            startActivity(new Intent(this, DetailActivity.class));
        });
    }
 }

値の例：

import com.quick.qt.spm.SpmAgent;

String transferValue = SpmAgent.getPageProperty(PAGE_NAME, "my_transfer_arg1", SpmAgent.transProperties);

注意：ページ属性は手動でタグ付けすることしかできません。

6.2 Activity ページの自動収集 (フルトラッキングポイント)

デフォルトでは、Activity ページで自動ページ収集が有効になっています。gradle プラグインを統合する必要はありません。SDK がセッションデータを収集すると、SDK は各アクティビティページのパスとページアクセス時間データをデフォルトで収集およびレポートします。開発者が同時にページパス手動収集 API `QtTrackAgent.onPageStart/onPageEnd` を呼び出すと、ページデータが繰り返しレポートされ、冗長なページパスデータが生成されます。`QtConfigure.preInit` 事前初期化関数を呼び出した直後に QtTrackAgent.disableActivityPageCollection() 関数を呼び出すことで、SDK がアクティビティページのパスデータを自動的に収集するのを防ぐことができます。

public static void disableActivityPageCollection();

アクティビティページの自動収集およびレポートインターフェイスのみを無効にしたい場合は、アクティビティの `onCreate` 関数でこの関数を呼び出す必要があります：

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.skipMe(this, null); 

6.3 Fragment ページの自動収集 (フルトラッキング)

デフォルトでは、Fragment ページはデータを自動的に収集しません。フルトラッキングプラグインを組み込み、自動収集を有効にする必要があります。具体的な操作を確認できます

8.1 全トラッキングポイント Gradle プラグインを導入する および Fragment の PV データの全トラッキングポイントを有効にする。

7. イベントトラッキングポイント

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

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

onEventObject インターフェイスを使用して、イベントに関する統計を収集します。パラメーター値は、String、Long、Integer、Float、Double、Short のいずれかの型です。

インターフェイス：

public static void onEventObject(Context context, String eventID, Map<String, Object> map)

public static void onEventObject(Context context, String eventID, Map<String, Object> map, String pageName)

アップロードするイベントの最大数

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

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

• カスタム属性マップ長 (パラメーター数)：100 キーと値のペア

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

数値の説明：

例：

import com.quick.qt.analytics.QtTrackAgent;

Map<String, Object> music = new HashMap<String, Object>();
music.put("music_type", "popular");// カスタムパラメーター：音楽の種類。値：ポピュラー
music.put("singer", "JJ"); // 歌手：(林俊傑) JJ
music.put("song_name","A_Thousand_Years_Later"); // 曲名：一千年以後
music.put("song_price",100); // 価格：100 元
QtTrackAgent.onEventObject(this, "play_music", music, "home_page");

備考：

• 現在のプルイベントのサンプルレート設定は、自動収集スイッチに依存します。SDK を使用するには、`setAutoEventEnabled()` メソッドを呼び出す必要があります。

  例：

  public class MyApplication extends Application {
  
      @Override
      public void onCreate() {
          super.onCreate();
  	QtConfigure.setCustomDomain("Your collection service domain name", null);
          // デバッグログを開きます。
          QtConfigure.setLogEnabled(true);
          // サンプルレートのプルは、フルトラッキングポイントのスイッチ設定に依存します。イベントのサンプルレート制御機能が必要な場合は、必要に応じてこの API を呼び出してください。
          QtTrackAgent.setAutoEventEnabled(false);        
          //...
      }
      //... 
  }

• 複数パラメーター型のイベントは、計算イベント/カウントイベントの元の分析シナリオを満たすことができます。

• 計算イベントのパラメーター型が異なると、計算方法も異なります。数値と文字の 2 つのカテゴリに分けることができます。

  • 数値型：累積値、最大値、最小値、平均値、重複排除の計算をサポートします。

  • 文字型：重複排除計算をサポートします。

7.2 子プロセスのトラッキング

SDK は、子プロセスのカスタムイベントトラッキングのみをサポートします。ページ収集などの他のタイプの収集はサポートされていません。子プロセスのトラッキングには、SDK の初期化後に `QtConfigure.setProcessEvent` 関数を呼び出す必要があります。

例：

public class MyApplication extends Application{
    @Override
    public void onCreate(){
        super.onCreate();
        // SDK を初期化します。
        QtConfigure.preInit(this, "Your appkey", "Application Marketplace");
        
        // 子プロセスでのカスタムイベントのカウントをサポートします。
        QtConfigure.setProcessEvent(true);
        // ...

注意：

• 子プロセスでカスタムイベントの統計を収集したい場合は、子プロセスで SDK を初期化する必要があります。

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

8.1 フルトラッキング Gradle プラグインの導入

buildscript {
    repositories {
        maven { url 'https://repo1.maven.org/maven2/' } // QuickTracking リポジトリ
        jcenter()
            google()
        }
    
    dependencies {
        classpath 'com.android.tools.build:gradle:3.5.4'
            
            // QuickTracking プラグイン android-gradle-plugin の依存関係を追加します。
            // Gradle 7.1.2 以降に対応します。
            //classpath 'com.umeng.umsdk:android-gradle-plugin:1.0.0' 
            // Gradle 7.1.2 から 7.5 に対応します。
            classpath 'com.lydaas.qtsdk:quick-gradle-plugin2:1.0.2'
            // Gradle 7.5 から 8 以降に対応します。
            // classpath 'com.lydaas.qtsdk:quick-gradle-plugin2:2.0.0'
            // Gradle 9 以降に対応します。
            // classpath 'com.lydaas.qtsdk:quick-gradle-plugin2:2.0.1'
        }
}

allprojects {
    repositories {
        maven { url 'https://repo1.maven.org/maven2/' } // QuickTracking リポジトリ
        jcenter()
            google()
        }
}

pluginManagement {
    repositories {
        google {
            content {
                includeGroupByRegex("com\\.android.*")
                includeGroupByRegex("com\\.google.*")
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
        maven { url 'https://repo1.maven.org/maven2/' }// QuickTracking リポジトリ
    }

}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url 'https://repo1.maven.org/maven2/' }// QuickTracking リポジトリ
    }
}

buildscript {
    dependencies {
        classpath 'com.lydaas.qtsdk:quick-gradle-plugin2:2.0.1'
    }
}

8.2 gradle を使用した依存関係とコンパイルプラグイン

メインモジュールの `build.gradle` 設定にフルトラッキングプラグインを適用します：

apply plugin: 'com.android.application'
// apply plugin: 'Plugin' // com.qt.analytics.plugin バージョン P のプラグイン (フルトラッキングシナリオ)
apply plugin: 'com.quick.analytics.plugin' // PX バージョンのプラグイン (フルトラッキングシナリオ)

dependencies {
   // Quick Tracking 統計 SDK を追加します。SDK のバージョンは上記の Gradle バージョンと一致する必要があります。
   // implementation 'com.umeng.umsdk:qt-common:1.4.4.P' //P. SDK のバージョンは x.x.x.P です。
   implementation 'com.lydaas.qtsdk:qt-px-common:1.8.6.PX' // PX バージョン (SDK のバージョンは x.x.x.PX)
}

8.3 フル埋め込み API

8.3.1 フル埋め込みスイッチ

PV データのフル Fragment トラッキングを有効にする

`enableFragmentPageCollection()` メソッドを使用して、すべての Fragment ページ閲覧イベントの自動収集を有効にできます。

/**
* Fragment ページの自動データ収集スイッチはデフォルトで無効になっています。
* @param enable true-有効; false-無効
*/
public static void enableFragmentPageCollection(boolean enable);

例：

import com.quick.qt.commonsdk.QtConfigure;
import com.quick.qt.analytics.QtTrackAgent;

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
	QtConfigure.setCustomDomain("Your collection service domain name", null);
        // デバッグログを開きます。
        QtConfigure.setLogEnabled(true);
        // すべての Fragment ページ閲覧イベントの自動収集を有効にします。
        QtTrackAgent.enableFragmentPageCollection(true);
        //...
    }
    //... 
}

Activity PV を有効にする

デフォルトでは、Activity ページの自動収集は有効になっています。SDK がセッションデータを収集すると、SDK は各 Activity ページのパスとページアクセス時間データを収集およびレポートします。開発者が同時にページパスを手動で収集する API `QtTrackAgent.onPageStart/onPageEnd` を呼び出すと、派生ページデータが繰り返しレポートされ、冗長なページパスデータが生成されます。`QtConfigure.preInit` 事前初期化関数を呼び出した直後に QtTrackAgent.disableActivityPageCollection() 関数を呼び出すことで、SDK が Activity ページのパスデータを自動的に収集するのを防ぐことができます。

public static void disableActivityPageCollection();

Activity ページの自動収集およびレポートインターフェイスのみを無効にしたい場合は、Activity の `onCreate` 関数でこの関数を呼び出す必要があります：

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.skipMe(this, null); 

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

Activity ページの自動収集およびレポートインターフェイスのみを無効にしたい場合は、Activity の `onCreate` 関数でこの関数を呼び出す必要があります：

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.skipMe(this, null); 

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

/**
 * イベントのサンプルレート設定をプルします。
 * コントロールクリックイベントを自動的に収集するかどうかを指定します。デフォルトでは、SDK はコントロールクリックイベントを自動的に収集しません。
 * @param enable true-自動収集; false-自動収集なし
 */
public static void setAutoEventEnabled(boolean enable);

例：

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.commonsdk.QtConfigure;

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
	QtConfigure.setCustomDomain("Your collection service domain name", null);
        // デバッグログを開きます。
        QtConfigure.setLogEnabled(true);
        QtTrackAgent.enableFragmentPageCollection(true);
        // コントロールクリックイベントの自動収集を有効にします。
        QtTrackAgent.setAutoEventEnabled(true);
        //...
    }
    //...
    
}

自動監視をサポートするコントロールタイプのリスト：

8.3.2 自動 Activity/Fragment PV 設定のカスタムプロパティ

特定の Activity/Fragment に対してインターフェイス `com.umeng.analytics.autotrack.PageAutoTracker` を実装することで、自動収集される Activity/Fragment ページのプロパティ、ページ名、またはソースページ名をカスタマイズできます。

public interface PageAutoTracker {
    /**
     * 現在のページの名前を返します。
     * @return カスタムページ名が必要ない場合は、null または空の文字列が返されます。
     */
    String getPageName();

    /**
     * ソースページ名を返します。
     * @return カスタムソースページ名が必要ない場合は、null または空の文字列が返されます。
     */
    String getRefPageName();

    /**
     * カスタムプロパティのキーと値のペアを返します。キーと値は両方とも文字列型でなければなりません。カスタムプロパティが存在しない場合は、null を返します。
     *
     * @return カスタム属性が存在しない場合は、null が返されます。
     */
    Map<String, String> getTrackProperties();
}

例：

import com.quick.qt.analytics.QtTrackAgent;

/**
 * FragmentContacts のカスタムページ名とプロパティを指定します。
 */
public static class FragmentContacts extends Fragment implements PageAutoTracker {
        private final String mPageName = "FragmentContacts";

        static FragmentSimple newInstance(int num) {
            FragmentSimple f = new FragmentSimple();

            // 引数として num を指定します。
            Bundle args = new Bundle();
            args.putInt("num", num);
            f.setArguments(args);

            return f;
        }

        /**
         * Fragment の UI は、インスタンス番号を示す背景のシンプルなテキストビューです。
         */
        @Override
        public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {

            FrameLayout fl = new FrameLayout(getActivity());
            fl.setLayoutParams(new FrameLayout.LayoutParams(FrameLayout.LayoutParams.MATCH_PARENT,
                    FrameLayout.LayoutParams.MATCH_PARENT));
            fl.setBackgroundColor(Color.LTGRAY);
            TextView tv = new TextView(getActivity());
            tv.setText("Fragment Contacts");
            tv.setTextColor(Color.BLACK);
            tv.setOnClickListener(new View.OnClickListener() {
                @Override
                public void onClick(View v) {
                    QtTrackAgent.ignoreView(v); // TextView コントロールによるデータの自動収集とレポートを無効にします。
                    Toast.makeText(getActivity(), "The text box was clicked", Toast.LENGTH_LONG).show();
                }
            });
            fl.addView(tv);
            return fl;
        }

        // FragmentContacts ページの名前をカスタマイズします。
        @Override
        public String getPageName() {
            return "FragmentContacts";
        }

    	// FragmentContacts のソースページ名をカスタマイズする必要はないので、直接 null を返します。
        @Override
        public String getRefPageName() {
            return null;
        }

    	// FragmentContacts ページのプロパティをカスタマイズします。
        @Override
        public Map<String, String> getTrackProperties() {
            Map<String, String> properties = new HashMap<>();
            properties.put("fragment_arg1", "fragment_value111");
            properties.put("fragment_arg2", "fragment_value222");
            return properties;
        }
    }

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

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

/**
* コントロールのカスタム属性を設定します。カスタム属性は複数の K-V キーと値のペアを設定できます。キーと値は両方とも文字列型でなければなりません。
* @param view コントロールオブジェクト
* @param properties カスタムプロパティ
*/
public static void setViewProperties(View view, JSONObject properties);

例：

import com.quick.qt.analytics.QtTrackAgent;

@QtDataTrackViewOnClick
public void onClick(View v) {
    int id = v.getId();
    Intent in = null;
    if (id == R.id.normal) {
        // Resource ID が normal の Button コントロールにカスタムイベント ID ekv_normal を設定します。
        // このパラメーターを設定すると、SDK レポートデータのイベント ID は「ekv_normal」になります。
        QtTrackAgent.setViewEventID(v, "ekv_normal");
        // normal Button コントロールと呼ばれる ekv_normal イベントのカスタムプロパティ値を設定します。
        // customArgs の属性と属性値は、ekv_normal イベントデータで一緒にレポートされます。
        JSONObject customArgs = new JSONObject();
        try {
            customArgs.put("customArg1", "value1111");
            customArgs.put("customArg2", "value2222");
        } catch (JSONException e) {
        
        }
        QtTrackAgent.setViewProperties(v, customArgs);
      }
   }

8.3.4 コントロールクリックイベントのカスタムイベントコードの設定

`setViewEventID()` メソッドを使用して、特定のコントロールのクリックイベントにカスタムイベントコードを設定できます。

/**
* 自動収集されるコントロールクリックイベントにカスタムイベントコードを設定します。
* @param view コントロールオブジェクト
* @param eventID カスタムイベントコード
*/
public void setViewEventID(View view, String eventcode);

例：

import com.quick.qt.analytics.QtTrackAgent;

@QtDataTrackViewOnClick
public void onButtonClick(View v) {
    int id = v.getId();
    Intent in = null;
    if (id == R.id.normal) {
       // Resource ID が normal の Button コントロールにカスタムイベントエンコーディング ekv_normal を設定します。
       // 設定後、このコントロールをクリックすると、SDK レポートデータのイベントコードは「ekv_normal」になります。
       QtTrackAgent.setViewEventID(v, "ekv_normal");
       //...
    }
}

8.3.5 `onClick` 属性で設定されたクリックイベントの処理

レイアウトファイルの `android:onClick` 属性で設定されたクリックコールバックメソッドが実行されると、コントロールクリックイベントは自動的にトリガーされません。このとき、`android:onClick` 属性に対応するメソッドに `@QtDataTrackViewOnClick` アノテーションを付けることで、メソッドが実行されたときに SDK が自動的にコントロールクリックイベントをトリガーできるようになります。例：

レイアウトファイル：

<Button
    android:id="@+id/normal"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_marginTop="24dp"
    android:onClick="onButtonClick"
    android:text="@string/ana_name"/>

onClick イベントのカスタムハンドラ関数：

import com.quick.qt.analytics.autotrack.QtDataTrackViewOnClick;

@QtDataTrackViewOnClick
public void onButtonClick(View v) {
    //...
}

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

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

/**
* viewType コントロールのクリックイベントの自動収集を無視します。
* このメソッドは複数回の呼び出しをサポートし、設定結果のコレクションを無視します。
* @param viewType
*/
public static void ignoreViewType(Class viewType);

例：

import com.quick.qt.analytics.QtTrackAgent;

// Button タイプのコントロールクリックイベントを無視します
QtTrackAgent.ignoreViewType(Button.class);

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

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

/**
* View オブジェクトのクリックイベントの自動収集を無視します。
*
* @param view オブジェクト。
*/
public static void ignoreView(View view);

例：

import com.quick.qt.analytics.QtTrackAgent;

Button myButton = (Button)findViewById(R.id.testButton);
// myButton コントロールのクリックイベントを無視します。
QtTrackAgent.ignoreView(myButton);

8.4 露出トラッキングポイント

自動露出追跡機能を使用する場合、ユーザーは設定項目で自動露出機能を手動でオンにする必要があります。

import com.quick.qt.analytics.QtTrackAgent;

// 露出統計を有効にします。
QtTrackAgent.enableExposureCollection();

もちろん、必要に応じて自動露出機能をオフにすることもできます。

// 露出統計を無効にします。
QtTrackAgent.disableExposureCollection();

8.4.1 露出設定項目

import com.quick.qt.analytics.exposure.QTExposureConfig;
import com.quick.qt.analytics.QtTrackAgent;

// 一般的な露出設定
QTExposureConfig config = new QTExposureConfig.Builder()
                . setMinDuration(300) // 最小露出表示時間 (ミリ秒)
                . setMinVisibleRatio(0.5f) /// 最小表示率
                . setRepeated(true) // 露出を繰り返すかどうかを指定します。
                . setCallback(new QTExposureConfig.ExposureCallback() { // 露出コールバック
                    @Override
                    public void onExposure(View view) {
                        Toast.makeText(mContext, "Exposure succeeded", Toast.LENGTH_SHORT).show();
                    }
                })
                .build();
        
QtTrackAgent.setExposureConfig(config);

次の表は、露出のプロパティを設定するための `QTExposureConfig` のパラメーターを説明しています：

8.4.2 グローバル露出の設定

`QtTrackAgent.setExposureConfig(config)` メソッドを使用して、グローバル露出属性を設定できます。以下を呼び出すことを推奨します。

import com.quick.qt.analytics.exposure.QTExposureConfig;
import com.quick.qt.analytics.QtTrackAgent;

// 一般的な露出設定
QTExposureConfig config = new QTExposureConfig.Builder()
                . setMinDuration(300) // 最小露出表示時間 (ミリ秒)
                . setMinVisibleRatio(0.5f) /// 最小表示率
                . setRepeated(true) // 露出を繰り返すかどうかを指定します。
                . setCallback(new QTExposureConfig.ExposureCallback() { // 露出コールバック
                    @Override
                    public void onExposure(View view) {
                        Toast.makeText(mContext, "Exposure succeeded", Toast.LENGTH_SHORT).show();
                    }
                })
                .build();
        
QtTrackAgent.setExposureConfig(config);

8.4.3 露出要素のマーキング

露出機能を使用するには、露出要素を手動でバインドする必要があります。`QtTrackAgent.addExposureView()` メソッドを呼び出して、露出要素のバインドを実現できます。

import com.quick.qt.analytics.QtTrackAgent;

  /**
   * 露出要素をマークします
   *
   * @param view 露出するビューのオブジェクト。
   * @param 露出データパラメーターを含むオブジェクト。
   * @return 戻り値はありません。
   */
public static void addExposureView(View view, QTExposureData data) {
    QtTrackAgent.addExposureView(view, data);
}

パラメーターの説明：

QTExposureData API：

// インポートするパッケージの名前。
import com.quick.qt.analytics.exposure.QTExposureData;

/**
 * 指定されたイベント名で露出データを初期化します。
 *
 * @param event イベントの名前。
 */
public QTExposureData(String event) 

/**
 * 指定されたイベント名とカスタム属性を使用して露出データを初期化します。
 *
 * @param event イベントの名前。
 * @param properties イベントのカスタムプロパティ。
 */
public QTExposureData(String event, Map<String, Object> properties) 

/**
 * 指定されたイベント名、カスタム属性、および露出設定で露出データを初期化します。
 *
 * @param event イベントの名前。
 * @param properties イベントのカスタムプロパティ。
 * @param exposureConfig 露出設定。
 */
public QTExposureData(String event,  Map<String, Object>  properties, QTExposureConfig exposureConfig) 

パラメーターの説明：

注意：

1. String 型のプロパティ名とプロパティ値。大文字と小文字のアルファベット、数字、アンダースコアのみがサポートされています！

2. プロパティ値は、次の Java 型のいずれかです：String、Long、Integer、Float、Double、Short。

3. 既存のグローバル属性のキーと同じキーの場合、既存の値は更新されます。異なるキーの場合は、新しいグローバル属性が挿入されます。

   例：

   import com.quick.qt.analytics.exposure.QTExposureData;
   
   Map<String, Object> properties = new HashMap<>();
   properties.put("param1", item.text); // カスタムパラメーター 1
   properties.put("param2", position); // カスタムパラメーター 2
   
   QTExposureData exposureData=new QTExposureData("Event encoding", properties)) 

一般要素タグ

サンプルコード：

import com.quick.qt.analytics.exposure.QTExposureData;
import com.quick.qt.analytics.QtTrackAgent;

// 露出データを構築します。
QTExposureData exposureData = new QTExposureData("exposure_view_click");
QtTrackAgent.addExposureView(imageView, exposureData);

リストクラス要素タグ

すべての要素をマークする

import com.quick.qt.analytics.exposure.QTExposureConfig;
import com.quick.qt.analytics.exposure.QTExposureData;
import com.quick.qt.analytics.QtTrackAgent;

// 露出データを構築します。
public void onBindViewHolder(@NonNull ViewHolder holder, final int position) {
    View view = holder.xxxx; 
    Map<String, Object> properties = new HashMap<>();
    properties.put("param1", item.text); // カスタムパラメーター 1
    properties.put("param2", position); // カスタムパラメーター 2
    QtTrackAgent.addExposureView(convertView, new QTExposureData(item.text, properties));
}

単一の要素をマークする：

import com.quick.qt.analytics.exposure.QTExposureConfig;
import com.quick.qt.analytics.exposure.QTExposureData;
import com.quick.qt.analytics.QtTrackAgent;

// 露出データを構築します。
public void onBindViewHolder(@NonNull ViewHolder holder, final int position) {
     View view = holder.xxxx; 
     if(item.text.contains("New")){
          Map<String, Object> properties = new HashMap<>();
          properties.put("$$item_reused_id","custom id"); // 単一の要素は、重複を避けるために現在の要素のカスタム ID をマークする必要があります
          properties.put("text", item.text); // カスタムパラメーター 1
          properties.put("position", position); // カスタムパラメーター 1
          QtTrackAgent.addExposureView(convertView, new QTExposureData(item.text, properties));
     }
}

8.4.4 露出要素の削除

要素自体が削除された場合、対応するトラッキングポイントの監視も削除されます (リストの削除など)。

もちろん、`QtTrackAgent.removeExposureView()` を使用して、露出収集が不要な要素を削除することもできます。

import com.quick.qt.analytics.QtTrackAgent;

/**
 * 指定されたイベント名とカスタム属性を使用して露出データを初期化します。
 *
 * @param view ラベル付けされた要素。
 * @param item_reused_id カスタム ID (カスタム要素 ID が渡された場合)
 */
QtTrackAgent.removeExposureView(view,"custom id"); 

9. シェア拡散

シェア拡散は、グロースハック戦略の重要な概念です。ユーザー間のソーシャルなつながりを利用して情報の相互伝達を実現し、新規ユーザーの獲得を促進します。

シェア拡散の SDK 機能の統合を完了すると、QuickTracking プラットフォームを使用して、シェアトレンドモデルを使用し、シェアリターン関連の指標によってマーケティング活動のプルアップ効果を測定できるようになります。

1. トップシェアユーザーと異なるシェアフローレベルのリフロー効果メトリックの表示をサポートします。

2. バックフロー指標の柔軟な組み合わせと設定をサポートし、最も分裂プルアップ能力とシェアバックフロー変換能力を持つトップユーザーを表示し、ユーザーのシェア拡散リンクとシェアバックフローの関係を追跡し、主要なオピニオンコンシューマーを迅速に特定します。

9.1 ソース共有パラメーターの取得

import com.quick.qt.analytics.QtTrackAgent;
/**
 * ソース共有パラメーター取得 API
 * @param context ホストアプリの ApplicationContext オブジェクト。指定する必要があります。
 * */
public static Map<String, String> getRefShareParams(Context context);

バージョン

Android SDK v1.6.0.PX バージョン以降

特徴

リクエスト共有パラメーターの前にソース共有 ID とソース共有 URL を取得するために使用される API

リクエストパラメーター

戻りパラメーター

呼び出し例

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.analytics.share.ShareResultHandler;

public class DemoActivity {
    ...
    public void onShare() {
        Context context = DemoActivity.this;
        Map<String, String> refShareParams = QtTrackAgent.getRefShareParams(context);
        String $$_ref_share_id = refShareParams.get("$$_ref_share_id");
        
        Map<String, String> shareParams = new HashMap<String, String>();
        shareParams.put("shareId", $$_ref_share_id);
        shareParams.put("title", "Share activity A");
        shareParams.put("campaign", "Share activity A");
        QtTrackAgent.requestShareParams(context, "https://www.taobao.com/productId", shareParams, 0, new ShareResultHandler() {
            @Override
            public void onShareResultSuccess(final JSONObject result) {
                try {
                    Log.i("Test", "shareParams = " + result.toString());
                    String $sid = result.getString("shareId");
                    Map<String, Object> properties = new HashMap<String, Object>();
                    properties.put("$$_share_id", $sid);
                    properties.put("$$_share_url", "https://www.taobao.com/productId"); 
                    properties.put("$$_share_title","Share activity A"); 
                    properties.put("$$_share_campaign_id", "This is a custom sharing activity");
                      // 
                    properties.put("$$_share_type", "Target platform for user-defined sharing");
                    QtTrackAgent.onEventObject(this, "$$_share", properties);
                    // これがバックグラウンドスレッドでの何らかの操作であると仮定します
                    new Thread(new Runnable() {
                        @Override
                        public void run() {
                            // いくつかのバックグラウンドタスクを実行します...

                            // UI を更新し、メインスレッドに切り替えます。
                            runOnUiThread(new Runnable() {
                                @Override
                                public void run() {
                                    // メインスレッドでダイアログを表示します
                                    AlertDialog.Builder builder = new AlertDialog.Builder(context);
                                    builder.setTitle("Share parameters");
                                    builder.setMessage(result.toString());
                                    builder.show();
                                }
                            });
                        }
                    }).start();
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }

            @Override
            public void onShareResultFail(Throwable t) {
                Log.i("Test", "fail = " + t.getMessage());
            }
        });
    }
    ...
}

9.2 共有パラメーターのリクエスト

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.analytics.share.ShareResultHandler;

/**
 * URL を共有して API を取得します。
 * @param context ホストアプリの ApplicationContext オブジェクト。指定する必要があります。
 * @param url ページの URL。このパラメーターを指定する必要があります。
 * @param params 可能な共有パラメーター。このパラメーターは null にできます。
 *    {
 * title: 共有のタイトル。値は null にできます。最大長は 4*1024 です。
 * campaign: 共有アクティビティ、null にできます、最大長 4*1024
 * shareId: ソース共有の ID。このパラメーターは null にできます。
 * ... 拡張予定
 *  }
 * @params timeout リクエストのタイムアウト期間。単位：秒。有効な値：0～10。0 と 10 を指定した場合、SDK はデフォルト値 3 を使用します。
 * @param callback コールバック結果オブジェクト。指定する必要があり、null にはできません。
 * */
public static void requestShareParams(Context context, String url, Map<String, String> params, int timeout,final ShareResultHandler callback)

バージョン

Android SDK v1.6.0.PX バージョン以降

特徴

リクエストは、共有チェーンに必要な共有 ID を構築するために使用されます。

リクエストパラメーター

コールバックインターフェイス `ShareResultHandler` は次のように定義されます：

public interface ShareResultHandler {
    // このメソッドは、共有パラメーターが正常に返されたときにコールバックを返します。
    void onShareResultSuccess(JSONObject result);
    // このメソッドは、共有パラメーターの共有に失敗したときにコールバックを返します。t.getMessage を使用して失敗の原因を取得できます。
    void onShareResultFail(Throwable t);
}

戻りパラメーター

呼び出し例

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.analytics.share.ShareResultHandler;

public class DemoActivity {
    ...
    public void onShare() {
        Context context = DemoActivity.this;
        Map<String, String> shareParams = new HashMap<String, String>();
        shareParams.put("shareId", "");
        shareParams.put("title", "Share activity A");
        shareParams.put("campaign", "Share activity A");
        QtTrackAgent.requestShareParams(context, "https://www.taobao.com/productId", shareParams, 0, new ShareResultHandler() {
            @Override
            public void onShareResultSuccess(final JSONObject result) {
                try {
                    Log.i("Test", "shareParams = " + result.toString());
                    String $sid = result.getString("shareId");

                    Map<String, Object> properties = new HashMap<String, Object>();
                    properties.put("$$_share_id", $sid);
                    properties.put("$$_share_url", "https://www.taobao.com/productId"); 
                    properties.put("$$_share_title","Share activity A"); 
                    properties.put("$$_share_campaign_id", "This is a custom sharing activity");
                    properties.put("$$_share_type", "User-defined sharing platform");
                    QtTrackAgent.onEventObject(this, "$$_share", properties);
                    
                    // これがバックグラウンドスレッドでの何らかの操作であると仮定します
                    new Thread(new Runnable() {
                        @Override
                        public void run() {
                            // いくつかのバックグラウンドタスクを実行します...

                            // UI を更新し、メインスレッドに切り替えます。
                            runOnUiThread(new Runnable() {
                                @Override
                                public void run() {
                                    // メインスレッドでダイアログを表示します
                                    AlertDialog.Builder builder = new AlertDialog.Builder(context);
                                    builder.setTitle("Share parameters");
                                    builder.setMessage(result.toString());
                                    builder.show();
                                }
                            });
                        }
                    }).start();
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }

            @Override
            public void onShareResultFail(Throwable t) {
                Log.i("Test", "fail = " + t.getMessage());
            }
        });
    }
}

9.3 イベントのレポートと共有

プリセットイベントコード `$$_share` を使用して共有イベントをレポートします。

例

import com.quick.qt.analytics.QtTrackAgent;

Map<String, Object> properties = new HashMap<String, Object>();
properties.put("$$_share_id", "Share ID obtained through the request sharing parameter API");
properties.put("$$_share_url", "https://www.taobao.com/productId"); 
properties.put("$$_share_title","Share activity A"); 
properties.put("$$_share_campaign_id", "This is a custom sharing activity");
properties.put("$$_share_type", "User-defined sharing platform");
QtTrackAgent.onEventObject(this, "$$_share", properties);

呼び出されたリンクにはキー「$sid」と値である共有 ID パラメーターを含める必要があることに注意してください。例：https://example.aliyun.com/path/to/content?$sid=123456"