TEへデータ送信の準備

基本知識ではTEへデータ送信を実施する前に理解すべきデータルールについて説明します。

必須情報ではTEへデータ送信の際に準備しなければならないシステムパラメーターについて説明します。

TE (ThinkingEngine) は、フルエンドでのデータ送信スキームを提供しています。

一般的に、TEへのデータ送信には以下の3つのステップがあります。まず、ビジネスニーズに基づいてデータ収集案を整理します（必要に応じて、当社のアナリストが支援することも可能です）。次に、エンジニアによりデータ収集案に基づいた実装を行います。最後に、データ送信の正確性を検証します。

また、データ送信の前に、TEの基礎的な理解が重要です。このドキュメントでは、データ送信に必要な知識についての概要を説明します。

なお、このドキュメントの対象者は、ビジネス側での担当者、エンジニア側の担当者、検証テスト担当者など、TEを用いる可能性のあるすべての方々が対象です。

1. 概要

TEは、フルエンドでのデータ送信スキームを提供しています。主なデータ送信の方法は以下の通りです。

• クライアントSDK
  • サーバーと通信せず、デバイス情報やユーザー行動に関する情報を比較的簡単に収集します
• サーバーSDK
  • サーバーと通信し、より正確なユーザー行動に関する情報を収集します
• データインポートツール
  • より一般的なデータ収集スキームであるLogBusを使用したサーバーSDKなどが利用されます
  • 通常は過去データのインポートに使用されます

一般的なアプリやWeb開発環境に合わせ、TEは以下のSDKを提供しています。

• React Native SDK
• Flutter SDK
• Original SDK
  • Android SDK
  • iOS SDK
• Third-party frameworks
  • Flutter
  • Reactive Native
• H5 development
  • JavaScript SDK
  • H5 and native SDK open solution

For small game development, we provide:

• Mainstream game engine support: Cocos Creator

For mobile game development, we provide:

• Unity SDK

サーバーレベルでの収集シナリオでは、サーバーSDKとLogBusの併用を推奨します。この方式では、データインポートの安定性、リアルタイム性、効率性において最も優れています。

異なる過去データを新たにインポートする、もしくは追加する必要がある場合、DataXを使用することを検討できます。しかし、LogBusとは異なり、DataXは常駐サービスではなく、新しいデータの生成を監視してリアルタイムにインポートすることができません。そのためデータのリアルタイム性を保証することはできません。DataXの利点は、比較的簡単な操作で複数のデータソースからのデータ送信をサポートしていることです。

また、FilebeatとLogstashを使用して過去データを収集し、ログデータをTEにインポートする場合は、Filebeat + Logstashを参照ください。

データ収集の方法を設計する際には、事業状況に応じてアプリの技術アーキテクチャとビジネスニーズに適した手法を選択することが望まれます。収集の方法についてのご質問は、TEの担当者にお問い合わせください。

2. 基本知識

2.1 TEデータモデル

データ送信の前に、まずTEのデータを理解する必要があります。

データ収集の方法の設計は、ビジネスの目的に応じて、収集すべきユーザー行動データ等を決定するプロセスです。例えば、ユーザーの課金状況を分析したい場合には、収集すべきなのはユーザーの課金行動データです。このようなユーザー行動は5W1Hで分類することができます。

ユーザー行動データは、TEにおいてユーザーデータとイベントデータで構成され、それぞれUser TableとEvent Tableに格納されます。ユーザーデータは、主に頻繁に変化しないユーザーの状態や属性が記述されます。一方イベントデータは、特定の行動イベントに関連する情報が記述されます。

そのため、データ収集の方法を検討する際には、ユーザーデータとイベントデータをTEに通知するタイミングやトリガーを決定する必要があります。それぞれの詳細は User features and event attributes settingを参照ください。

すべてのデータ送信ガイドでは、ユーザーデータとイベントデータをそれぞれアクセスする方法を説明しています。

2.2 ユーザー識別ルール

ユーザーデータとイベントデータは、それぞれがどのユーザーに属しているかを指定する必要があります。アカウントシステムがないアプリの場合には、デバイス関連のIDを使用してユーザーを識別します。一方アカウントシステムがあるアプリの場合には、ユーザーが複数デバイスで単一のアカウントを用いてデータを生成する場合があります。このような場合において分析では、複数デバイスを横断してユーザーデータを分析することが好ましく、デバイス関連のIDを使用することは不適切です。

上記の2つのシナリオに対応するため、データ送信において2つのユーザーIDを組み合わせてユーザーを識別しています。

• Guest ID (#distinct_id)
  • クライアント側でランダムなGuest IDを生成、ユーザーを識別します。
• Account ID (#account_id)
  • ユーザーがログインした際にアカウントIDを任意に設定することができます。Account IDを用いることで複数デバイスのデータを紐づけることができます。

TEに格納されるデータには、Guest IDかAccount IDのいずれかを含める必要があります。クライアントSDKでは、デフォルトでGuest IDをランダムで生成します。Account IDを設定するためにloginを呼び出し、Account IDが設定されると、すべてのデータでどちらのIDも報告されます。サーバーレベルでは、少なくとも1つのIDを報告する必要があります。

またTEでは、ユーザーを識別するユニークなIDであるTE user ID (#user_id field)が設定されます。データが報告されると、 User identification rules に応じて、新しいIDが設定されるか、既存のIDが紐づけられます。

ユーザー識別ルールは非常に重要です。上記のIDが正しく設定されていないと、データが誤ったユーザーと紐づけられ、分析効果に影響を与えます。データ送信の前に、ルールをよく理解し、データ収集の際にも、ユーザー識別に関する設定を完了してください。

2.3 データルール

データ送信の方法に関係なく、データ送信の際には統一されたデータルールによって制限されます。データルールでは、データフォーマットとそれぞれの制限について説明します。

SDKを介してデータをアクセスする場合には、対応するインターフェイスを呼び出すことで、SDKはアクセスに必要なデータフォーマットにデータを整理します。データインポートツールやRestful APIを用いてデータ送信する場合には、データルールの説明に従ってデータを整理する必要があります。

またデータフォーマットに関しては、命名ルールとプロパティ値のデータ型には特別な注意を払う必要があります。

• 命名ルール
  • イベント名やプロパティ名には、文字、数字、アンダースコアのみを含めることができます。また50文字を超えることはできません

Note: プロパティ名では大文字と小文字が区別されません。一方イベント名とプロパティ値では大文字と小文字が区別されます。

• プロパティ値のデータ型

データ型	サンプル	備考	データ型
Numerical value	123,1.23	データ上限： -9E15 to 9E15	Number
Text	"ABC", "Tokyo"	データ上限：2KB	String
Time	"2019-01-01 00:00:00","2019-01-01 00:00:00.000"	"Yyyy-MM-dd HH: mm: ss. SSS " or "yyyy-MM-dd HH: mm: ss" 日付をしたい場合: "yyyy-MM-dd 00:00:00"	String
Boolean	true,false	-	Boolean
List	["a","1","true"]	リストの要素は文字列として識別されます。 The elements in the list will be converted to a string type, and the most in the list	Array(String)
Object	{hero_name: "Liu Bei", hero_level: 22, hero_equipment: ["Male and Female Double Sword", "Lu"], hero_if_support: False}	オプジェクトのKeyは独自のデータ型を有します。その説明は一般的な 属性 を参照してください。 オブジェクト内のKeyの上限は100個です。 Each child attribute (Key) in the object has its own data type. Please refer to the general attribute of the corresponding type above for the value selection description · Up to 100 child attributes within the object	Object
Object group	[{hero_name: "Liu Bei", hero_level: 22, hero_equipment: ["Male and Female Double Sword", "Lu"], hero_if_support: False}, {hero_name: "Liu Bei", hero_level: 22, hero_equipment: ["Male and Female Double Sword", "Lu"], hero_if_support: False}]	オブジェクトグループのKeyは独自のデータ型を有します。その説明は一般的な 属性 を参照してください。 オブジェクトグループ内のKeyの上限は500個です。 Each child attribute (Key) in the object group has its own data type. For value selection description, please refer to the general attributes of the corresponding type above Up to 500 objects in the object group	Array(Object)

Note：TEでは、プロパティ値のデータ型は、最初に受信したプロパティ値のデータ型に従って決定されます。値のデータ型がデータ内のあるプロパティと予め決定されたデータ型と一致しない場合には、そのプロパティを破棄する必要があります。

TEには、#で始まるプロパティ名があり、そのようなプロパティはプリセットプロパティであり、特別な設定を必要とせず、SDKではデフォルトで収集しています。詳細は Preset attribites and system fields を参照してください。

データフォーマットやデータ型が正しく設定されていない場合には、データが格納できないことに注意してください。そのため、データ送信の際、またデータ検証の際には Data Reporting Management module を用いてデータの正確性を確認、管理する必要があります。

3. 必須情報

エンジニアによって正式にデータ送信が行われる前に、以下の情報が準備されていることを確認してください。

1. Project APP ID

• TEでプロジェクトを作成すると、プロジェクト毎にAPP IDが生成されます。プロジェクト管理画面から確認することができます。

2. Address of the data receiving end

• SaaSバージョンを用いている場合には、「https://ta-receiver.thinkingdata.io」です
• 個別構築の場合には、プライペートクラスタ（またはアクセスポイント）にドメイン名を紐付け、SSL証明書を発行する必要があります

1. Address of the data receiving endの確認方法
2. 以下のURLにアクセスし、OKと表示されるかを確認してください
3. https://YOUR_RECEIVER_URL/health-check
4. データ収集の整理

• データ収集の方法
  • クライアントSDK、サーバーSDK、データインポートツール、または複数の方法の組み合わせを明確化してください
  • データ送信するデータの内容とトリガータイミング

データ送信の前に理解すべきドキュメントの読み込みが完了しました。これで、選択したデータ収集の方法の基づいて、対応するアクセスガイドを参照しながら、データ送信を開始してください。