メインコンテンツまでスキップ

応用ガイド

最終更新 2026/10/05

1. ユーザーIDの設定​

SDKインスタンスは、デフォルトで乱数を各ユーザーのデフォルトのゲストIDとして使用します。このIDは、ユーザーが未ログインの状態での識別IDとして使われます。なお、ゲストIDはユーザーがキャッシュを削除した場合やデバイスを変更した場合に変わります。

1.1 ゲストIDの設定​

ヒント

通常、ゲストIDをカスタマイズする必要はありません。ユーザー識別ルールを理解したうえで、ゲストIDを設定してください。

Appにユーザーごとの独自のゲストID管理体系がある場合は、setDistinctIdを呼び出してゲストIDを設定できます：

// ゲストIDをThinkerに設定
TDAnalytics.setDistinctId("Thinker");

現在のゲストIDを取得する必要がある場合は、getDistinctIdを呼び出して取得できます：

//ゲストIDを返す
let distinctId = TDAnalytics.getDistinctId();

設定する場合は、初期化の前にこのインターフェースを呼び出す必要があります

1.2 アカウントIDの設定​

ユーザーがログインしたときにloginを呼び出して、ユーザーのアカウントIDを設定できます。AEプラットフォームはアカウントIDを優先して識別子として使用します。設定したアカウントIDは保存され、loginを複数回呼び出すと以前のアカウントIDが上書きされます：

//ユーザーのログインの一意な識別子です。このデータは送信データの#account_idに対応し、この場合#account_idの値はTAになります
TDAnalytics.login("TA");

このメソッドはユーザーのログインイベントを送信しませんのでご注意ください

1.3 アカウントIDのクリア​

ユーザーがログアウトした後にlogoutを呼び出して、アカウントIDをクリアできます。次にloginを呼び出すまでは、ゲストIDが識別IDとして使われます：

// 送信データから"#account_id"を削除し、以降のデータには"#account_id"が含まれなくなります
TDAnalytics.logout();

このメソッドはユーザーのログアウトイベントを送信しませんのでご注意ください

2. イベントの送信​

2.1 通常イベント​

trackを直接呼び出してカスタムイベントを送信できます。事前に整理したドキュメントに従って、イベントのプロパティと送信条件を設定することをお勧めします。ここでは商品の購入を例にします：

TDAnalytics.track({
    eventName: "product_buy", // イベント名
    properties: {
        product_name: "商品名"
    } //イベントプロパティ
});
  • trackインターフェースには2つのパラメーターがあり、1つ目はイベント名、2つ目はイベントのプロパティです
  • イベント名は文字列で、英字で始まり、数字、英字、アンダースコア"_"のみを含めることができます。最大長は50文字で、英字の大文字と小文字は区別されません。
  • イベントのプロパティはJSオブジェクトで、各要素が1つのプロパティを表します。
  • 要素のnameはプロパティ名に対応し、英字で始まり、数字、英字、アンダースコア"_"のみを含めることができます。最大長は50文字で、英字の大文字と小文字は区別されません。
  • 要素のValueはそのプロパティの値で、String、Number、Boolean、Date、Object、Arrayに対応しています。Objectの内容にはString、Number、Boolean、Date、Array（内容は文字列）を、Arrayの内容にはObjectとStringを使用できます

2.2 初回イベント​

初回イベントとは、デバイスまたはその他のディメンションのIDに対して、1回だけ記録されるイベントのことです。たとえば、あるデバイスで最初に発生したイベントを記録したい場合は、初回イベントでデータを送信できます。

TDAnalytics.trackFirst({
    eventName: "device_activation",
    properties: { key: "value" }
});

デバイス以外のディメンションで初回かどうかを判定したい場合は、初回イベントにfirst_check_idを設定できます。たとえば、あるアカウントの初回イベントを記録する必要がある場合は、アカウントIDを初回イベントのfirst_check_idに設定します:

// ユーザーIDを初回イベントのfirst_check_idに設定し、ユーザーの初回アクティベーションイベントを収集します
TDAnalytics.trackFirst({
  eventName: "account_activation",
  firstCheckId: "TA",
  properties: { key: "value" }
});

注意：初回かどうかの検証はサーバー側で行われるため、初回イベントはデフォルトで1時間遅れて取り込まれます。

2.3 更新可能イベント​

更新可能イベントを使用すると、特定のシナリオでイベントデータを変更する必要がある場合に対応できます。更新可能イベントでは、そのイベントを識別するIDを指定し、更新可能イベントのオブジェクトを作成する際に渡す必要があります。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。

// 例：更新可能なイベントを送信します。イベント名はUPDATABLE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
TDAnalytics.trackUpdate({
  eventName: "UPDATABLE_EVENT",
  properties: { status: 3, price: 100 },
  eventId: "test_event_id"
});

// 送信後、イベントプロパティstatusは5に更新され、priceは変わりません
TDAnalytics.trackUpdate({
  eventName: "UPDATABLE_EVENT",
  properties: { status: 5 },
  eventId: "test_event_id"
});

2.4 上書き可能イベント​

上書き可能イベントは更新可能イベントと似ていますが、上書き可能イベントでは最新のデータで過去のデータを完全に上書きする点が異なります。効果としては、前のデータを削除して最新のデータを格納するのと同じです。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。

// 例：上書き可能なイベントを送信します。イベント名はOVERWRITE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
TDAnalytics.trackOverwrite({
  eventName: "OVERWRITE_EVENT",
  properties: { status: 3, price: 100 },
  eventId: "test_event_id"
});

// 送信後、イベントプロパティstatusは5に更新され、priceプロパティは削除されます
TDAnalytics.trackOverwrite({
  eventName: "OVERWRITE_EVENT",
  properties: { status: 5 },
  eventId: "test_event_id"
});

2.5 共通イベントプロパティ​

ユーザーのデバイスID、流入チャネル、ユーザーステータスなどの重要なプロパティは、すべてのイベントに設定する必要があります。その場合、これらのプロパティを共通プロパティ、つまりすべてのイベントに含まれるプロパティとして設定できます。イベントを送信する前に、共通プロパティを設定しておくことを推奨します。

共通プロパティには、共通イベントプロパティと動的共通プロパティの2種類があります。イベントの送信時に、共通プロパティはデータのpropertiesに挿入されます。このとき、共通プロパティとイベントで設定したカスタムプロパティに同じkeyがある場合は、次の優先順位に従ってどの値を採用するかが判断されます：カスタムプロパティ>動的共通イベントプロパティ>静的共通イベントプロパティ>プリセットプロパティ

2.5.1 静的共通イベントプロパティ​

共通イベントプロパティとは静的な共通プロパティのことで、設定時には定数のみを渡すことができ、変化しない安定したプロパティの設定に適しています。setSuperPropertiesを呼び出して共通イベントプロパティを設定できます。共通イベントプロパティの形式の要件はイベントプロパティと同じです。

プロパティの優先順位では、カスタムプロパティは共通イベントプロパティよりも優先されます。そのため、共通イベントプロパティをあるプロパティのデフォルト値として使用し、変更が必要なイベントで同名のKeyを設定してデフォルト値を上書きすることもできます。

// 共通イベントプロパティを設定すると、すべてのデータのイベントにこれらのプロパティが含まれます
TDAnalytics.setSuperProperties({
     channel: "チャネル名",
     user_name: "ユーザー名"
});

setSuperPropertiesを複数回呼び出して共通イベントプロパティを設定した場合、同名のフィールドは後の呼び出しによって以前の値が上書きされ、名前が異なるフィールドは保持されます。

共通イベントプロパティを削除する場合は、unsetSuperProperty()を呼び出して共通イベントプロパティを1つクリアできます。すべての共通イベントプロパティをクリアしたい場合はclearSuperProperties()を、すべての共通イベントプロパティを取得したい場合はgetSuperPropertiesを呼び出します。

// 静的共通イベントプロパティを取得
var superProperties = TDAnalytics.getSuperProperties();
// 静的共通イベントプロパティを1つクリアします。たとえば、以前に設定した'channel'プロパティをクリアすると、以降のデータにはこのプロパティが含まれなくなります
TDAnalytics.unsetSuperProperty("channel");
// すべての静的共通イベントプロパティをクリア
TDAnalytics.clearSuperProperties();

2.5.2 動的共通イベントプロパティ​

動的共通プロパティは、イベントの送信時にfunctionを実行し、その戻り値を動的共通プロパティの値としてイベントに追加します。setDynamicSuperPropertiesインターフェースを呼び出して動的共通プロパティを設定できます。このインターフェースはfunctionをパラメーターとして受け取ります。

// 動的共通プロパティでUTC時間をイベントプロパティとして送信します
TDAnalytics.setDynamicSuperProperties(() => {
  var localDate = new Date();
  return {
    utcTime: new Date(
      localDate.getTime() + localDate.getTimezoneOffset() * 60000
    )
  };
});

functionはJSオブジェクトを返す必要があり、その各要素が1つのプロパティを表します。プロパティの形式の要件はイベントプロパティと同じです。

2.6 イベントの所要時間の記録​

timeEventを呼び出して計測を開始できます。計測したいイベント名を設定しておくと、そのイベントを送信したときに、記録した所要時間を表す#durationプロパティがイベントプロパティに自動的に追加されます。単位は秒です。

//次の例では、ユーザーがある商品ページに滞在した時間を集計します
TDAnalytics.timeEvent({
    eventName: "stay_shop"
});
/**do someting
    .......
**/
//ユーザーが商品ページを離れると計測が終了し、"stay_shop"イベントにイベントの所要時間を表すプロパティ#durationが付与されます
TDAnalytics.track({
    eventName: "stay_shop",
    properties: {
        product_name: "商品名"
    }
});

3. ユーザープロパティ​

3.1 userSet​

一般的なユーザープロパティは、userSetを呼び出して設定できます。このインターフェースで送信したプロパティは、既存のプロパティ値を上書きします。そのユーザープロパティが以前に存在しない場合は、新しく作成されます

// usernameはTA
TDAnalytics.userSet({
    properties: {
        username: "TA" 
    }
});
//usernameはAE
TDAnalytics.userSet({
    properties: {
        username: "AE" 
    }
});

プロパティの形式の要件は、イベントプロパティと同じです。

3.2 userSetOnce​

送信するユーザープロパティを一度だけ設定すればよい場合は、userSetOnceを呼び出して設定できます。そのプロパティにすでに値がある場合、この情報は無視されます。

//first_payment_timeは2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({
    properties: {
        first_payment_time: "2018-01-01 01:23:45.678" 
    }
});
//first_payment_timeは引き続き2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({
    properties: {
        first_payment_time: "2018-12-31 01:23:45.678" 
    }
});

プロパティの形式の要件は、イベントプロパティと同じです。

3.3 userAdd​

数値型のプロパティを送信する場合は、userAddを呼び出してそのプロパティを累積加算できます。そのプロパティがまだ設定されていない場合は、0を代入してから計算します

//この時点でtotal_revenueは30
TDAnalytics.userAdd({
    properties: {
        total_revenue: 30
    }
});
//この時点でtotal_revenueは678
TDAnalytics.userAdd({
    properties: {
        total_revenue: 648
    }
});

設定するプロパティのkeyは文字列で、Valueには数値のみ指定できます。

3.4 userUnset​

ユーザーのあるユーザープロパティ値をクリアする場合は、userUnsetを呼び出して、指定したプロパティをクリアできます。そのプロパティがまだクラスター内で作成されていない場合、userUnsetはそのプロパティを作成しません

// このユーザーの、ユーザープロパティ名がuserPropertykeyのユーザープロパティ値をクリアします（NULLに設定）
TDAnalytics.userUnset({
    property: "userPropertykey"
});

userUnsetに渡す値は、クリアするプロパティのKey値です。

3.5 userDelete​

あるユーザーを削除する場合は、userDeleteを呼び出してそのユーザーを削除できます。削除後はそのユーザーのユーザープロパティを照会できなくなりますが、そのユーザーが発生させたイベントは引き続き照会できます

TDAnalytics.userDelete();

3.6 userAppend​

userAppendを呼び出して、Array (List)型のユーザーデータに要素を追加できます。

TDAnalytics.userAppend({
    properties: {
        user_list: ["apple", "ball"]
    }
});

注意：この機能はAEプラットフォーム2.5以降のバージョンと組み合わせて使用する必要があります

3.7 userUniqAppend​

v2.1.0以降、userUniqAppendを呼び出して、Array (List)型のユーザーデータに要素を重複排除して追加できます。

//この時点でuser_listのプロパティ値は["apple"，"ball"]
TDAnalytics.userAppend({
    properties: {
        user_list: ["apple", "ball"]
    }
});
//この時点でuser_listのプロパティ値は["apple","apple","ball","cube"]
TDAnalytics.userAppend({
    properties: {
        user_list: ["apple", "cube"]
    }
});
//この時点でuser_listのプロパティ値は["apple"，"ball","cube"]
TDAnalytics.userUniqAppend({
    properties: {
        user_list: ["apple", "cube"]
    }
});

注意：この機能はAEプラットフォーム3.6以降のバージョンと組み合わせて使用する必要があります

5. その他の機能​

5.1 デバイスIDの取得​

getDeviceId()を呼び出してデバイスIDを取得できます。実行環境の都合上、デバイスIDはローカルキャッシュに保存されます。ユーザーがキャッシュを削除するとデバイスIDが変更されるため、デバイスIDが変わらないことは保証できません

var deviceId = TDAnalytics.getDeviceId();

5.2 onCompleteコールバック関数​

track, userSet, userSetOnce, userAdd, userDeleteなどのインターフェースでは、onCompleteコールバックを渡すことができます。

元のパラメーターリストの後ろに直接onCompleteを渡すことも、パラメーターオブジェクトを使うこともできます。パラメーターオブジェクトを使う場合は、パラメーターオブジェクトにonCompleteを含める必要があります。含めないとパラメーターエラーになります。

イベントの送信を例にします：

TDAnalytics.track({
  eventName: "test", // 必須
  properties: { testkey: 123 }, // 任意
  time: new Date(),
  onComplete: res => {
    console.log(res);
  }
});

onCompleteのパラメーターresはobject型で、codeとmsgの2つのプロパティがあります。

res.codeはint型で、次のように定義されています:

  • 0: 成功
  • -1: データ形式が正しくありません
  • -2: APP IDが無効です
  • -3: ネットワークまたはサーバーの異常

Debugモードでは次のように定義されています:

  • 0: 成功
  • -1: パラメーターまたは権限の検証に関する問題
  • 1: フィールドの基本的なエラーを示します。エラーのあるフィールドとその理由が詳しく返されます
  • 2: データ全体のエラーを示します
  • -3: ネットワークまたはサーバーの異常

res.msgはres.codeの説明文です。

5.3 イベントのキャッシュ送信の設定​

v2.2.0以降、初期化時にイベントのキャッシュ送信を有効にするよう設定できます。

// AE SDKの設定オブジェクト
var config = {
  appId: "YOU-APP-ID", // プロジェクトのAPP ID
  serverUrl: "https://youserverurl.com", // データの送信先URL
  enableBatch: true, // イベントのキャッシュ一括送信を有効にするかどうか。true=有効、false=無効
  batchConfig: {
    size: 5, // イベントのキャッシュ送信件数
    interval: 5000 // イベントのキャッシュ送信間隔（ミリ秒）
  }
};
// 初期化
TDAnalytics.init(config);

6. チャネルSDKとの互換性​

6.1 Tencent Ads​

6.1.1 ソリューションの概要​

TDAnalytics SDKを統合すれば、Tencent Ads SDKを別途統合する必要はありません。TDAnalyticsの初期化メソッドを実行すると、Tencent Ads SDKの初期化が自動的にトリガーされます。登録や課金などの重要なイベントを送信すると、設定に従ってこれらのイベント情報がTencent Adsに自動的に送信されます。

6.1.2 接続手順​

  1. Tencent Ads SDKをダウンロードします。現在使用しているのは1.5.4ですが、他のバージョンに変更してもかまいません。

dn-sdk-minigame.cjs.jsをTDAnalytics SDKと同じディレクトリに配置します。

  1. 初期化
注記

TDAnalytics SDKのバージョンは3.0.4以上である必要があります

TDAnalytics.init({
    appId: 'AppId',
    serverUrl: 'ServerUrl',
    tgaInitParams: {
        user_action_set_id: 100001,// データソースID。数値、必須
        secret_key: '5e853xxxxxxd57a690xxxxxxxxxx',// 暗号化key。必須
        appid: 'wx123xyz123xyz123x',//WeChatミニゲームのAPPID。wxで始まる。必須
    },
    reportingToTencentSdk: 2,//1 Tencentのみに送信 2 TencentとAEの両方に送信 3 AEのみに送信
    debugMode: 'debug'// debugモードの場合、Tencent Ads SDKのローカルデバッグログを出力します
})
  1. ユーザーIDの設定
  • setOpenId

openidは通常、バックエンドのインターフェースを呼び出して非同期で取得します（openidの取得方法）。openidを取得したら、*sdk.setOpenId()*メソッドを呼び出して設定してください。openidとunionidはどちらか一方しか設定できず、openidを優先して設定します。

wx.request({
    url: 'openidの取得と登録ユーザーかどうかの判定を行うバックエンドインターフェースのURL', 
    success: function(res){
        if(res.openid){ 
          // openidを設定します。登録行動を送信する前に、必ずopenidを設定してください。setOpenIdは同期メソッドのため、設定後すぐに登録行動を送信できます。            
          TDAnalytics.login(res.openid);
          
          //登録行動を送信します。登録ユーザーかどうかはバックエンドのインターフェースで判定します
          if(res.isRegisterUser){
           TDAnalytics.track({
                eventName: "REGISTER"
            });
          }
        }
    }
});
  • setUnionId

unionidは通常、バックエンドのインターフェースを呼び出して非同期で取得します（unionidの取得方法）。unionidを取得したら、*sdk.setUnionId()*メソッドを呼び出して設定してください。このメソッドでunionidを設定する必要があるのは、openidがない場合のみです。

wx.request({
    url: 'openidの取得と登録ユーザーかどうかの判定を行うバックエンドインターフェースのURL', 
    success: function(res){
        if(res.unionid){ 
          // unionidを設定します。openidを優先して使用し、openidがない場合、またはバックエンドでunionidに統一している場合にのみ設定してください。           
          TDAnalytics.setDistinctId(res.unionid);
          
          //登録行動を送信します。登録ユーザーかどうかはバックエンドのインターフェースで判定します
          if(res.isRegisterUser){
           TDAnalytics.track({
                eventName: "REGISTER"
            });
          }
        }
    }
});
  1. 行動の送信
TDAnalytics.track({
    eventName: "product_buy", // イベント名
    properties: {
        product_name: "商品名"
    } //イベントプロパティ
});

次の特定のイベントの場合は、指定のイベント名で送信する必要があります

イベントイベント名イベントプロパティ（そのうちのkeyを含める必要があります）

ミニゲームの起動

START_APP

なし

課金

PURCHASE

{

value: 600

}

登録

REGISTER

休眠ユーザーの復帰

RE_ACTIVE

{

backFlowDay: 30

}

ミニゲームをお気に入りに追加

ADD_TO_WISHLIST

{

type: 'default',

}

ミニゲームの共有

SHARE

{

target: 'APP_MESSAGE'

}

キャラクターの作成

CREATE_ROL

{

name: 'SuperMan'

}

チュートリアルの完了

TUTORIAL_FINISH

なし

ゲームのレベルアップ

UPDATE_LEVEL

{

level: 2,

power: 85,

}

ショップページの閲覧

VIEW_CONTENT

{

// 重要シナリオへのアクセス：ショップ

item: 'Mall',

}

ゲーム内イベントの閲覧

VIEW_CONTENT

{

// 重要シナリオへのアクセス：イベント

item: 'Activity',

}

たとえば、ゲームのレベルアップイベントを送信する場合

TDAnalytics.track({
    eventName: "UPDATE_LEVEL", 
    properties: {
        level: 2,
        power: 85,
    }
});
このページは役に立ちましたか？
このページの内容