# TD Android および iOS SDK 用 Cordova Plugin

Cordova Plugin は、TD Android および iOS mobile SDK を使用して Ionic app プラットフォーム上で event を tracking できるようにします。td-cordova-sdk は、ネイティブの iOS および Android SDK を内部で使用して、Treasure Data と Cordova app 間のブリッジを提供する module です。

より詳細なドキュメントは、[td-android-sdk](https://github.com/treasure-data/td-android-sdk) および [td-ios-sdk](https://github.com/treasure-data/td-ios-sdk) の GitHub リポジトリでご覧いただけます。

Treasure Data では、本番環境で使用を開始する前に、Treasure Data JavaScript SDK version 3 を使用してサイトでの新しい機能の実装を検証することをお勧めします。cookie の管理方法が異なります。これらの記事の多くを参照する際は、提案されている event collector と Treasure Data JavaScript SDK version 3 の呼び出しをソリューションで定義する必要があることに注意してください。例えば、//cdn.treasuredata.com/sdk/2.5/td.min.js を //cdn.treasuredata.com/sdk/3.0.0/td.min.js に変更します。

* [Plugin のインストール](#installing-the-plugin)
* [Plugin メソッドの使用](#using-the-plugin-methods)
* [Plugin の設定](#configuring-the-plugin)
* [Local Buffer への Event の追加](#add-an-event-to-local-buffer)
* [Buffer された Event の TreasureData への Upload](#upload-buffered-events-to-treasuredata)
* [Custom Event の追加と Upload](#add-and-upload-custom-events)
* [App Lifecycle Event の自動 Tracking (Android のみ)](#track-app-lifecycle-events-automatically-android-only)
* [In-App Purchase Event の自動 Tracking](#track-in-app-purchase-events-automatically)
* [各 Event への Device の UUID の自動追加](#add-the-uuid-of-the-device-to-each-event-automatically)
* [各 Event Record への UUID の自動追加](#add-a-uuid-to-each-event-record-automatically)
* [各 Event Record への Advertising Id の自動追加](#add-the-advertising-id-to-each-event-record-automatically)
* [各 Event への Device Model 情報の自動追加](#add-the-device-model-information-to-each-event-automatically)
* [各 Event への Application Package Version 情報の自動追加](#add-application-package-version-information-to-each-event-automatically)
* [各 Event への Locale 設定情報の自動追加](#add-locale-configuration-information-to-each-event-automatically)
* [Server Side Upload Timestamp の使用](#use-server-side-upload-timestamp)
* [Session の Tracking の開始/終了](#startend-tracking-a-session)
* [Profile API](#profile-api)
* [Debug Log の有効化と無効化](#enable-and-disable-debug-log)
* [Retry Uploading の有効化と無効化](#enable-and-disable-retry-uploading)
* [Device と OS のサポート](#device-and-os-support)


## Plugin のインストール

以下のコードを使用して Cordova plugin をインストールします。

```bash
cordova plugin add td-cordova-sdk
```

## Plugin メソッドの使用

plugin をインストールした後、`cordova.plugins.TreasureDataPlugin` namespace を通じてメソッドにアクセスできます。

## Plugin の設定

以下の**フィールド**を正しい情報で編集します。

```javascript
    TreasureDataPlugin.setup({
      apiEndpoint: '<https://in.treasure-data.com',> // またはその他のサポートされている endpoint
      encryptionKey: '<xxxxx>',
      apiKey: '<xxxxx>', /// Write-only API key を使用してください
      defaultDatabase: '<default_database>',
      defaultTable: '<default_table_name>',
      cdpEndpoint: '<https://cdp.in.treasuredata.com'> // またはその他の cdp endpoint
    })
```

## Local Buffer への Event の追加

以下の例に示すように、特定の database と table に custom event を追加できます。event をインポートする database と table を指定します。database 名と table 名の合計長は 129 文字未満である必要があります。

```javascript
const customEvent = {event: 'Custom event', data: new Date().getSeconds()};
TreasureDataPlugin.addEvent(customEvent, 'table', 'database');
// または
TreasureDataPlugin.addEvent(customEvent, 'table');
```

database パラメータが指定されていない場合、`TreasureDataPlugin.setup({...})` の `defaultDatabase` 設定が代わりに使用されます。

オプションとして、`addEvent` が成功したか失敗したかを知る必要がある場合は、代わりに `addEventWithCallback` を使用します。database パラメータとして `null` または `undefined` を渡すことができ、`TreasureDataPlugin.setup({...})` の `defaultDatabase` 設定が代わりに使用されます。

```javascript
const customEvent = {
    event: 'Custom event',
    data: new Date().getSeconds()
};
TreasureDataPlugin.addEventWithCallback(customEvent, 'table', 'database', () => {
    console.log('Add Event Successfully');
}, (errorCode, errorMessage) => {
    console.log('Add Event Failed', errorCode, errorMessage);
});
```

## Buffer された Event の TreasureData への Upload

`uploadEvent` 関数を使用して、いつでもすべての buffer された event を Treasure Data に upload できます。

```javascript
TreasureDataPlugin.uploadEvents();
```

オプションとして、`uploadEvents` が成功したか失敗したかを知る必要がある場合は、代わりに `uploadEventsWithCallback` を使用します。

```javascript
    TreasureDataPlugin.uploadEventsWithCallback(() => {
      console.log('Upload events successfully')
    }, (errorCode, errorMessage) => {
      console.log('Failed to upload events', errorCode, errorMessage);
    });
```

## Custom Event の追加と Upload

Custom event の追加と upload は、デフォルトで有効になっています。この機能はいつでも無効化および有効化できます。

custom event を無効化するには:

```javascript
TreasureDataPlugin.disableCustomEvent();
```

custom event を有効化するには:

```javascript
TreasureDataPlugin.enableCustomEvent();
```

## App Lifecycle Event の自動 Tracking (Android のみ)

この機能は Android でのみ利用できます。App lifecycle event の tracking はオプションであり、デフォルトでは有効になっていません。以下を使用して app lifecycle event を自動的に tracking できます:

```javascript
TreasureDataPlugin.enableAppLifecycleEvent();
```

```javascript
TreasureDataPlugin.disableAppLifecycleEvent();
```

app lifecycle event の tracking が有効かどうかを確認するには:

```javascript
TreasureDataPlugin.isAppLifecycleEventEnabled((enabled) => {
    console.log('Tracking app lifecycle event is enabled?', enabled ? 'yes' : 'no');
})
```

## In-App Purchase Event の自動 Tracking

この機能の API を呼び出す際にプラットフォームをチェックする必要はありません。単に no-op になります。
In-app purchase event の tracking はオプションであり、デフォルトでは有効になっていません。

in-app purchase event を自動的に tracking するには:

```javascript
TreasureDataPlugin.enableInAppPurchaseEvent();
```

in-app purchase event の tracking を無効化するには:

```
TreasureDataPlugin.disableInAppPurchaseEvent();
```

in-app purchase eventのtrackingが有効かどうかを確認するには:

```javascript
TreasureDataPlugin.isInAppPurchaseEventEnabled((enabled) => {
  console.log('Tracking in app purchase event is enabled?', enabled ? 'yes' : 'no');
})
```

## デバイスのUUIDを各イベントに自動的に追加する

以下の呼び出しにより、デバイスのUUIDが各イベントに自動的に追加されます。この値はアプリケーションがアンインストールされるまで変更されません。

```javascript
TreasureDataPlugin.enableAutoAppendUniqId();
```

デバイスのUUIDを各イベントに自動的に追加するのを無効にするには:

```javascript
TreasureDataPlugin.disableAutoAppendUniqId();
```

デバイスのUUIDをリセットするには:

```javascript
TreasureDataPlugin.resetUniqId();
```

## 各イベントレコードにUUIDを自動的に追加する

以下の呼び出しにより、各イベントレコードにUUIDが自動的に追加されます。各イベントは異なるUUIDを持ちます。

```javascript
    TreasureDataPlugin.enableAutoAppendRecordUUID();
```

各イベントレコードへのUUIDの自動追加を無効にするには:

```javascript
TreasureDataPlugin.disableAutoAppendRecordUUID();
```

## 各イベントレコードにAdvertising Idを自動的に追加する

以下の呼び出しにより、Advertising Idが各イベントレコードに自動的に追加されます。

```javascript
TreasureDataPlugin.enableAutoAppendAdvertisingIdentifier();
// またはカスタムカラムを指定
TreasureDataPlugin.enableAutoAppendAdvertisingIdentifier('custom_aaid_column');
```

**Android**では、この機能を動作させるためにGoogle Play Service Ads (Gradle `com.google.android.gms:play-services-ads`)を依存関係としてインストールする必要があります。**iOS**では、この機能を動作させるためにLink Binary With LibrariesビルドフェーズでAd Supportフレームワークをリンクする必要があります。

ユーザーがデバイスでLimit Ad Tracking機能を有効にしている場合、Treasure DataはAdvertising Idをレコードに追加しません。

Advertising Idの取得が非同期であるため、各レコードへのadvertising IDの追加を有効にした後、Advertising Idがレコードに追加できるようになるまで時間がかかる場合があります。ただし、Treasure DataはAdvertising Idをcacheするため、Advertising Idの取得taskの完了を待たずに次のイベントに追加できます。

Advertising Idの追加を無効にするには:

```javascript
TreasureDataPlugin.disableAutoAppendAdvertisingIdentifier();
```

## デバイスモデル情報を各イベントに自動的に追加する

デバイスモデル情報を各イベントに自動的に追加するには:

```javascript
TreasureDataPlugin.enableAutoAppendModelInformation();
```

デバイスモデル情報の追加を無効にするには:

```javascript
TreasureDataPlugin.disableAutoAppendModelInformation();
```

## アプリケーションパッケージバージョン情報を各イベントに自動的に追加する

アプリケーションバージョン情報を各イベントに自動的に追加するには:

```javascript
TreasureDataPlugin.enableAutoAppendAppInformation();
```

アプリケーションバージョン情報の各イベントへの自動追加を無効にするには:

```javascript
TreasureDataPlugin.disableAutoAppendAppInformation();
```

## ロケール設定情報を各イベントに自動的に追加する

ロケール設定情報を各イベントに自動的に追加するには:

```javascript
TreasureDataPlugin.enableAutoAppendLocaleInformation();
```

ロケール設定情報の各イベントへの自動追加を無効にするには:

```javascript
TreasureDataPlugin.disableAutoAppendLocaleInformation();
```

## Server Side Upload Timestampを使用する

アプリケーションがaddEventを呼び出したときに記録されるclient deviceの時刻に加えて、server sideのupload timestampの記録を有効にしたい場合は、以下を使用します:

```javascript
TreasureDataPlugin.enableServerSideUploadTimestamp();
// またはカスタムカラムを指定
TreasureDataPlugin.enableServerSideUploadTimestamp('custom_server_side_upload_timestamp_column');
```

server side upload timestampの記録を無効にするには:

```javascript
TreasureDataPlugin.disableServerSideUploadTimestamp();
```

## Sessionのtrackingを開始/終了する

sessionのtrackingを開始するには:

```javascript
TreasureDataPlugin.startSession(sessionTable, sessionDatabase);
```

現在のsessionのtrackingを終了するには:

```javascript
TreasureDataPlugin.endSession(sessionTable, sessionDatabase);
```

## Profile API

この機能はデフォルトではアカウントで有効になっていません。

この例に示すように、TreasureDataのsharedInstanceのプロパティとしてcdpEndpointを設定する必要があります:

```javascript
    var plugin = cordova.plugins.TreasureDataPlugin;
    function success(response) {
      /* response format => [
        {
          "segments": ["segment_id"],
          "attributes": {
            "age": ##,
            "td_client_id": "xxxxxxxxxxxxx"
          },
          "audienceId": "audience_id",
          "key": { "name": "user_id", "value": "xxxxxxx" }
        },
        {
          "segments": ["segment_id", "segment_id"],
          "attributes": {
            "im_segments": "xxxxxxxxxxxx",
            "work_style_per_family": "xxxxxxxx"
          },
          "audienceId": "audience_id",
          "key": {
            "name": "td_client_id",
            "value": "xxxxxxxxxxxxx"
          }
        }
      ] */

      // yay
    }

    function error() {
      // nay
    }

    plugin.fetchUserSegments(
      ["audience_id","audience_id"],
      {
        user_id: "xxxxx",
        td_client_id: "xxxxx"
      },
      success,
      error
    );
```

## Debug Logを有効化/無効化する

debug logを有効にするには:

```javascript
TreasureDataPlugin.enableLogging();
```

debug logを無効にするには:

```javascript
TreasureDataPlugin.disableLogging();
```

## Retry Uploadingを有効化/無効化する

retry uploadingを有効にするには:

```javascript
TreasureDataPlugin.enableRetryUploading();
```

retry uploadingを無効にするには:

```javascript
TreasureDataPlugin.disableRetryUploading();
```

# デバイスとOSのサポート

サポートされているデバイスとOSの詳細については、native SDKsのリポジトリを参照してください。