Locationモジュール | モジュール | Tealium開発者ドキュメント

Locationモジュールを使用すると、Androidアプリが位置情報を受信し、ジオフェンスを構成および監視できるようになります。位置追跡とジオフェンシングの詳細については、こちらを参照してください。

サポートされているプラットフォーム

以下のプラットフォームがサポートされています。

要件

Tealium for Android（5.6.0以降）
Google Play Services Location（11.0.0以降）

このモジュールはFirebase Cloud Messagingをサポートしています。

サンプルアプリ

当社のライブラリ、トラッキングメソッド、ベストプラクティスの実装に精通していただけるよう、Android Locationモジュールのサンプルアプリをご確認いただけるようになっています。

インストール

このモジュールをMavenによって（推奨）、または手動でインストールします。インストールした後で、次のインポートステートメントを追加します。

import com.tealium.location.TealiumLocation;

Maven

Mavenを使用してモジュールをインストールするには：

プロジェクトの最上位のbuild.gradleファイルに、次のMavenレポジトリを追加します。

maven {
      url "https://maven.tealiumiq.com/android/releases/"
}

プロジェクトモジュールのbuild.gradleファイルに、Tealiumライブラリ、Locationモジュール、およびGoogle Play Services Location APIのMaven依存関係を追加します。

dependencies {
      implementation 'com.tealium:library:5.8.0'
      implementation 'com.tealium:location:1.0.0'
      runtimeOnly 'com.google.android.gms:play-services-location:17.0.0'
}

手動

Locationモジュールを手動でインストールするには：

Locationモジュールをダウンロードします。
最上位のbuild.gradleファイルで、以下を検証します。

allprojects {
      repositories {
          ...
          google()
          flatDir {
              dirs 'libs'
          }
          ...
      }
}

ファイルtealium.location-1.0.0.aarをプロジェクトの<PROJECT_ROOT>/<MODULE>/libsディレクトリにコピーします。
Tealiumライブラリの依存関係をプロジェクトモジュールのbuild.gradleファイルに追加します。

dependencies {
      // only required if you do not already have this reference
      implementation(name:'tealium-5.6.0', ext:'aar')
      // location module reference
      implementation(name:'tealium.location-1.0.0', ext:'aar')
      // Google's Location Services API reference
      runtimeOnly 'com.google.android.gms:play-services-location:17.0.0'
  }

初期化

Tealium インスタンス名を TealiumLocation.setupInstance()に渡して、Location モジュールを初期化します。

Set<String> tealiumInstances = new HashSet<>();
tealiumInstances.add(TealiumHelper.TEALIUM_MAIN);

mInstance = TealiumLocation.setupInstance(this, tealiumInstances);

位置追跡

Location モジュールは、有効化され、位置情報へのアクセス許可を付与されると、継続的な位置追跡を自動的に実行します。位置情報の更新は、精度と時間間隔という2つの構成に基づいています。

精度は高または低に構成できます。高精度はAndroid構成のPRIORITY_HIGH_ACCURACYに対応し、低精度はAndroid構成のPRIORITY_BALANCED_POWER_ACCURACYに対応します。

Android位置情報の精度構成の詳細については、こちらを参照してください。

位置情報の更新間隔は、ミリ秒単位の値で構成されます。アプリにとって好適な範囲内で可能な限り高い値を使用してください。間隔の値は、AndroidのsetInterval()およびsetFastestInterval()メソッドに渡されます。

Android位置情報の間隔構成の詳細については、こちらを参照してください。

位置追跡を開始するには、 TealiumLocation.startLocationUpdates()を呼び出します。最初のパラメータを高精度のトラッキングの場合はtrue、精度を下げたトラッキングの場合はfalseに構成します。

次の例では、高精度と60000ミリ秒（60秒）の時間間隔を使用します。

TealiumLocation.getInstance().startLocationUpdates(true, 60000);

継続的な位置追跡を無効にするには、 TealiumLocation.destroyInstance() または TealiumLocation.stopLocationUpdates()メソッドを呼び出します。

位置情報へのアクセス許可

アプリで、位置情報へのアクセス許可を付与するには:

位置情報リクエストコードの定数変数を構成するには:

public static final int LOCATION_REQUEST_CODE = 101;

アプリの MainActivity クラスに次のメソッドを追加します:

public void requestLocationPermission() {
        if (ContextCompat.checkSelfPermission(getApplicationContext(),
        Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
            ActivityCompat.requestPermissions(this,
              new String[]{
                  Manifest.permission.ACCESS_FINE_LOCATION,
                  Manifest.permission.ACCESS_COARSE_LOCATION
              }, LOCATION_REQUEST_CODE);
        }
    }

requestLocationPermission() メソッドを onCreate() メソッド (MainActivity クラス) の中で呼び出します。

if ((ContextCompat.checkSelfPermission(getApplicationContext(),
      Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED)
      && ContextCompat.checkSelfPermission(getApplicationContext(),
      Manifest.permission.ACCESS_COARSE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
          requestLocationPermission();
  }

任意で、位置情報へのアクセス許可が付与されたことを確認するには、 onRequestPermissionsResult() メソッドをオーバーライドします:

@Override
public void onRequestPermissionsResult(int requestCode,
      String[] permissions,
      int[] grantResults) {
        String message;
        if (requestCode == LOCATION_REQUEST_CODE) {
            // If request is cancelled, the result arrays are empty.
            if ((grantResults.length > 0) && (grantResults[0]
              == PackageManager.PERMISSION_GRANTED)) {
                message = "Location Permission Granted";
            } else {
                message = "Location Permission Not Granted";
            }
        } else {
            message = "Location Permission Not Granted";
        }
        showToast(message);
  }

private void showToast(String message) {
      Toast.makeText(getApplicationContext(),
      message,
      Toast.LENGTH_LONG).show();
}

最後に認識された位置

継続的な位置追跡が無効になっている場合は、メソッド TealiumLocation.requestDeviceLastLocation()を使用して、最後に認識された位置をリクエストします。このメソッドは、デバイス上の他のアプリによって精度を確保する目的で使用されているロケーションクライアントに依存します。他のアプリが最新の位置情報を受信していない場合、このメソッドは最後に認識された位置情報（またはその位置情報が使用不可の場合はnull）を返します。

TealiumLocation.getInstance().requestDeviceLastLocation();

ジオフェンシング

ジオフェンシングを有効にして初期化するには、次のいずれかの方法で、ジオフェンスJSONファイルをセットアップメソッドに指定します。

ホスト型URL メソッド TealiumLocation.setupInstanceWithUrl()への URL として指定されている独自のホスト型ジオフェンスファイルを使用します。このオプションは、公開構成URLをオーバーライドした場合、またはホスト型データレイヤーを使用する必要がある場合に推奨されます。

TealiumLocation.setupInstanceWithUrl(this, tealiumInstances, "https://example.com/geofences.json");

ローカルファイル アプリの Assets ディレクトリに保存されているジオフェンスファイルを TealiumLocation.setupInstanceWithFile()で使用します。

TealiumLocation.setupInstanceWithFile(this, tealiumInstances, "geofences.json");

追加の検討事項

バッテリー最適化機能 バッテリー最適化機能を実装しているAndroidデバイスは、ジオフェンスモニタリングに支障をきたし、イベントが発動しない原因になる可能性があります。

BroadcastReceiver ジオフェンス遷移タイプがトリガーされると、GEOFENCE_EVENTブロードキャストが送信されます。Androidは、複数のBroadcastReceiverが定義されている場合でも、_最初_のレシーバのみをこの特定のブロードキャストに対して呼び出します。GEOFENCE_EVENTブロードキャストに対応したサードパーティSDKの場合は、GEOFENCE_EVENTブロードキャストの各レシーバのonReceive()メソッドを呼び出す「プロキシ」BroadcastReceiverを実装します。

ジオフェンスの初期化 作成時にユーザーがジオフェンス内にいる場合、"enter"遷移イベントはトリガーされません。これは、"exit"および"enter"の遷移イベントが境界を横断するときにトリガーされ、境界内に存在するときにはトリガーされないためです。

遅延： ジオフェンシング機能を使用するときは、次の点を考慮してください。

ジオフェンスサービスは位置情報を継続的に照会しないため、アラートを受信する際に遅延が生じることが予想されます。遅延は通常2分未満ですが、バックグラウンドの位置情報制限が構成されている場合、またはデバイスが一定の期間静止していた場合は、遅延が増加します。
ジオフェンスサービスは、ネットワーク位置情報プロバイダーとデータコネクトに依存しています。ジオフェンス内に信頼できるネットワーク接続がない場合は、アラートがトリガーされない可能性があります。
Wi-Fiがデバイスでオフになっている場合、ジオフェンスの半径、デバイスモデル、Androidのバージョンなどの構成によっては、アプリケーションがジオフェンスアラートを受信しないことがあります。Android 4.3以降では、「Wi-Fiスキャンのみモード」機能が提供され、ユーザーはWi-Fiを無効にしても、信頼性の高いネットワーク位置情報を受信できるようになっています。この構成を有効にするようユーザーに促すことをお勧めします。

アクティブなジオフェンスの数 ジオフェンスは、可能な限り少ないリソースを使用して動的に追加および削除されます。定義できるジオフェンスの数に制限はありませんが、アクティブなジオフェンスの数は、実行中の_全_アプリケーションにわたって、デバイスユーザーあたり100個までに制限されています。

データレイヤー

以下の変数は、モバイルデータレイヤーの一部としてLocationモジュールによって値が入力されます。これらの変数はライブラリから自動的に各トラッキングコールに含まれます。

変数名	型	説明	例
`latitude`	`String`	最後に記録されたユーザーの位置の緯度	`"32.906119"`
`longitude`	`String`	最後に記録されたユーザーの位置の経度	`"-117.2367"`
`location_accuracy`	`String`	Locationモジュールの精度構成（`"high"`、`"low"`など）	`"high"`

ジオフェンシング中にユーザーの遷移状態が変化すると、位置データを含むトラッキングコールが送信されます。遷移状態の変化には、指定された期間にユーザーがジオフェンス内に進入、退出、滞留することなどが含まれます。AndroidメソッドsetLoiteringDelay()を使用して、滞留アラート送信の基準とする徘徊期間を構成する必要があります。

以下の変数がデータレイヤーに送信されます。

変数名	型	説明	例
`tealium_event`	`String`	Tealiumのトラッキング対象ジオフェンスイベント	`"geofence_entered"`、`"geofence_exited"`、または`"geofence_dwell"`
`geofence_name`	`String`	ジオフェンス地域の名前	`"Tealium_San_Diego"`
`geofence_transition_type`	`String`	ジオフェンス遷移イベントのタイプ	`"geofence_entered"`、`"geofence_exited"`、または`"geofence_dwell"`

APIリファレンス

Location モジュールで使用されるメソッドのリファレンスについては、Tealium SDK for Android API の TealiumLocation クラスを参照してください。