terra-mobile-sdk

Terra API モバイル SDK

iOS、Android、React Native、Flutter で Terra API モバイル SDK を統合するためのガイダンスです。ワークフローと、クロスプラットフォームで注意すべき点はすべてここ（SKILL.md）に記載されています。プラットフォームごとの設定の詳細（機能、マニフェストのエントリー、インストール座標、コードスニペット、プラットフォーム固有の動作）は references/ に記載されています。

アカウントツール：CLI または MCP

モバイル連携では、アカウントツールを使ってバックエンドが保持する認証情報を提供し、デバイスが実際に登録されたことを確認します。

一度だけ行うセットアップ。 ユーザーごとのトークンを発行するバックエンドには、独自の認証情報が必要です。

terra environments list --select dev_id,name                    # the dev-id the app is built against
terra data-tokens create --env <dev-id> --name mobile --scopes auth:write

必要なだけ何度でも行える動作確認。 これらは読み取り専用で、認証情報を出力しません。

terra data-tokens list --env <dev-id> --select token_id,name,scopes,expires_at,last_used_at,revoked_at
terra users list --env <dev-id> --provider APPLE --select user_id,reference_id,active

data-tokens list が表示するのはメタデータのみです。これが適切な確認方法である理由は、有効なトークンが存在するか、そのスコープが何かを示しつつ、ベアラーを再表示しないためです。再表示には、別途 keys:read が必要な terra data-tokens retrieve-secret を使います。

トークン発行経路を手動で試す場合。 これは読み取り操作ではありません。initConnection() が受け取る有効期間の短いトークンを発行し、表示します。

terra data-api /auth/tokens -X POST -q reference_id=<your id>

ここでの reference_id はクエリパラメーターなので、-q を使います。-d で渡すと、エンドポイントが読み取らない JSON 本文に含まれます。それでも呼び出しは成功し、どのユーザーにもひも付いていないトークンが返されます。トークンをひも付けることで、デバイスが誤ったユーザーに関連付けられるのを防げるため、これは重要です。ひも付けられた場合、トークンはその識別子に関連付けられ、トークンの引き換え時には SDK から送信された値は無視されます。（/auth/generateWidgetSession は本文を受け取るため、こちらでは -d が適切です。決めつけずに terra admin-api list --data-api <path> --format json で確認してください。）

バックエンドがまだない段階で、フロー全体を最初から最後まで確認するのに便利ですが、標準出力に認証情報が表示されるため、CI ログに残さないようにしてください。

リファレンスファイルと出荷済み SDK のバージョンでは POST /auth/generateAuthToken が使われています。これはこのエンドポイントの非推奨の表記であり、パラメーターもレスポンスも同一です。リリース済み SDK がそのパスを使うため、期限を設けずに維持されています。どちらも使えますが、新しいコードでは /auth/tokens を使ってください。

環境の API キーが本当に必要な場合に限り、terra environments retrieve-api-key を使ってください。モバイルフローで必要になることはなく、webhook 署名シークレットも一緒に表示されます。

管理者トークンや環境の API キーをアプリに含めないでください。 SDK が受け取るのは、ユーザーごとに発行される有効期間の短い認証トークンです。terra data-tokens create --scopes auth:write は、バックエンドでトークンを発行するための、明示的にスコープが設定された取り消し可能な認証情報です。環境ごとに複数共存できるため、新しいトークンを発行してから古いトークンを取り消せばよく、切り替え時の停止は発生しません。MCP 経由でデータトークンを発行するには、ダッシュボードでユーザーの承認が必要であり、既定の MCP サインインでは許可されないアクセスレベルも必要になります。そのため、この手順だけは CLI のほうが簡単です。

デバイスの接続後、terra users list --reference-id <ref> でレコードが作成され、有効な状態を保っているかを確認できます。これにより、SDK の問題と権限の問題を切り分けられます。

コーディングエージェント（Claude Code、Codex、Cursor など。ユーザーのマシンまたはクラウド上で動作）では CLI を使い、インストールされていない場合はインストールを案内してください。macOS と Linux では curl -fsSL https://cli.tryterra.co/install.sh | sh、Windows PowerShell では irm "https://cli.tryterra.co/install.ps1" | iex を使います。ユーザーがすでに Homebrew または npm を使っている場合は、そちらを使ってもかまいません。チャットアシスタント（claude.ai、Claude Desktop、ChatGPT）では、コードを実行できる場合でも Terra API 管理 MCP サーバーを使ってください。サンドボックスから CLI のインストールやサインインはできません。各管理コマンドは、名前と method で対応付けられたツールです（terra users list は method: "list" を指定する users_read です）。terra data-api、terra admin-api、terra examples が使えるのは CLI のみで、--select と --jq に相当する MCP の機能はありません。terra-cli と terra-mcp のスキルには、ガードレール（変更の確認、トランスクリプトへの認証情報の記載防止）、エラー、およびタスクごとの手順書が含まれています。これらは連携の管理に使うものであり、このスキルで説明する API 呼び出しの代わりにはなりません。

モバイル SDK が適したケース

モバイル SDK の目的は一つだけです。Web API がないヘルスデータソースに接続することです。SDK が必要なのは、次の 3 つの連携のみです。

• Apple Health / HealthKit（iOS）
• Samsung Health（Android）
• Health Connect（Android）

その他のプロバイダー（Garmin、Fitbit、Oura、Whoop、Strava、Dexcom、その他 500 以上）には、SDK ではなく Unified API を通じて接続します。Google Fit は SDK 経由で Health Connect を使って読み取れますが、Web API のほうが推奨され、より信頼性の高い方法です。必要なプロバイダーに Web API がある場合は、Web API を使用してください。

SDK が取得したデータは、Web API のデータと同じ Data Destination（Webhook）に送られ、接続も同じ認証モデルで管理されます。受信する Webhook の構築やヘルスデータの保存を行う場合は、terra-unified-api スキルの担当範囲です。このスキルでは、デバイス上での接続を扱います。BLE または ANT+ ウェアラブルからの秒単位のライブデータには別の Real-Time SDK を使用します。これは terra-streaming で扱います。

6 つのステップで進めるワークフロー

どのプラットフォームでも手順は同じです。プラットフォームごとの違いは references/ ファイルに記載されています。

1. SDK をインストールし、ネイティブ機能を許可します。 パッケージを追加し、HealthKit／バックグラウンド機能（iOS）、またはマニフェストの権限と minSDK 28（Android）を宣言します。プラットフォームごとのリファレンスを参照してください。
2. アプリの起動時とフォアグラウンドへの復帰時に、毎回 SDK を初期化します。 TerraManager（iOS／Android）を作成するか、initTerra（RN／Flutter）を呼び出します。この呼び出しは非同期で、ほかの SDK 呼び出しより先に完了する必要があります。初期化はほかのすべての処理の前提となるため、インストール時に一度だけではなく、アプリを開くたびに実行してください。
3. ご自身のバックエンドで、1 回限りの認証トークンを発行します。 POST https://api.tryterra.co/v2/auth/tokens（非推奨の /auth/generateAuthToken も同じエンドポイントです）を呼び出します。トークンをユーザーに紐付けるため、ユーザー識別子を reference_id クエリパラメーターとして指定します。上記の「Account tools」にある auth:write データトークンを Authorization: Bearer terra_dt_... として送信し、認証します。このトークンは単一の環境に紐付いているため、dev-id ヘッダーは不要です。リファレンスファイルに記載されている dev-id と x-api-key の組み合わせも引き続き使用できますが、これは環境のマスターキーです。トークンは 1 回限り使用でき、3 分で期限切れになります（レスポンスに expires_in が含まれます）。そのため、アプリの起動時ではなく、ユーザーが接続を開始したときに都度発行してください。ご自身の経路を通じてクライアントに渡します。開発時も本番環境でも、このエンドポイントをアプリから呼び出してはいけません。トークンを発行できる認証情報は、必ずサーバー上に保管してください。
4. initConnection で接続を開始します。 接続の種類、トークン、権限セットを渡します。これにより OS の権限ポップアップが表示されます。下記の「権限ポップアップの動作」を参照してください。これは連携で最もユーザーの負担が大きい部分です。
5. 再初期化のたびに getUserId で検証します。 getUserId は同期処理で、接続中なら user_id、接続されていなければ nil／null を返します。各初期化の直後に呼び出し、nil の場合は initConnection を再度呼び出して再接続します。すでに接続されているユーザーを再接続してもポップアップは表示されず、ユーザーの操作も中断されません。
6. iOS のみ：バックグラウンド配信を有効にします。 AppDelegate の didFinishLaunchingWithOptions で Terra.setUpBackgroundDelivery() を呼び出します。これを行わないと、Apple Health のデータは自動的にプッシュされません。

認証解除には、Web 連携と同じエンドポイント DELETE /auth/deauthenticateUser を使用し、バックエンドから呼び出します。Web API の認証リファレンスを参照してください。

権限ポップアップの動作（リリース前にお読みください）

• ポップアップが表示されるのは一度だけです。 Apple Health と Health Connect のどちらでも、OS が権限画面を表示するのは最初の一度だけです。initConnection を再度呼び出しても、ポップアップには影響しません。再度表示されるのは、次の場合に限られます。（a）customPermissions のセットを拡張して initConnection を呼び出した場合、（b）アプリを削除して再インストールした場合、または（c）Health Connect のみ：リリース時に Google がアプリに承認していない権限をリクエストした場合。
• HealthKit のポップアップは WebView です。 アプリ自体が WebView ベースの場合は、WebView を中断して initConnection を呼び出し、完了後に WebView を再度開く必要があります。そうしないと、ポップアップを表示できません。
• getUserId が nil を返す場合は、再接続が必要であり、ポップアップが再表示されるわけではありません。 すでに権限を付与されているユーザーの再接続では、何も表示されません。

バックグラウンド配信（iOS）

Terra.setUpBackgroundDelivery() は Apple Health の自動プッシュを有効にしますが、配信には次の制約があります。

• アプリが終了している場合、発生頻度が大幅に低くなります。
• スマートフォンのロックが解除されている場合にのみ発生します。
• ネットワーク接続がある場合にのみ発生します。
• Terra API ダッシュボードで有効にしたデータ型のみを配信します。terra unified-api data scopes list --env <dev-id> でそのセットを確認できます。変更するには、terra unified-api data scopes replace に完全なセットを渡します。含めなかった型はすべて選択解除されるため、まず一覧を確認し、追加する型を含めて再度送信してください。
• customPermissions を使用する場合、バックグラウンド配信にはカテゴリごとに特定の権限を有効にする必要があります。Daily には STEPS、Sleep には SLEEP_ANALYSIS、Body には BMI と HEART_RATE、Activity には WORKOUT_TYPE、Nutrition には NUTRITION_CALORIES が必要です。

schedulerOn はiOS では効果がありません。バックグラウンド配信は setUpBackgroundDelivery() のみで制御されます。Android では、schedulerOn = true にすると、アプリがフォアグラウンドにある間に Terra API がスケジュールされたリクエストを実行できます。

クロスプラットフォームでの注意点

• Samsung Health を利用するには、承認済みのパートナーシップが必要です。 Terra API は Health Connect を介さない特権的な Samsung とのパートナーシップを結んでいますが、アクセスを申請する必要があります。承認を待つ間は Health Connect を使って開発してください。後から Samsung との直接連携に切り替えても、必要なのはバージョンの更新だけで、コード変更は不要です。リリースビルドには ProGuard ルール -keep class com.samsung.android.** { *; } が必要です（これがないと R8 が Samsung クラスを削除し、実行時にクラッシュします）。また、テスト端末では Samsung Health の開発者モードを有効にしてください。
• Health Connect にはマニフェストの設定と Google の承認が必要です。 マニフェストには、ACTION_SHOW_PERMISSIONS_RATIONALE および VIEW_PERMISSION_USAGE のインテントフィルターを含む、プライバシーポリシー用の <activity> が必要です。公開前に、Health Connect のデータ型へのアクセスを Google に申請し、使用しない権限ごとに tools:node="remove" を指定した <uses-permission> の行を追加する必要があります。references/android.md を参照してください。
• setIgnoredSources は iOS 専用で、設定は保存されません。 HealthKit で特定のソースアプリのデータを除外します（ユーザーが Terra API のクラウド接続と、そのプロバイダーのコンパニオンアプリの両方を Apple Health に同期していて、データが重複する場合に便利です）。アプリを再起動するたびにリセットされるため、初期化のたびに呼び出してください。Android では何も行いません。
• 新しい端末や再インストールで接続が置き換わる場合は、user_reauth を処理してください。 SDK の認証情報が、既存の接続と同じ (dev-id, reference_id, provider) を持ちながら新しい端末識別子を持つ場合（2 台目の端末、またはベンダー ID がリセットされた再インストール）、Terra API は新しい user_id を発行し、そのタプルに属する以前の接続をすべて削除して、old_user と new_user を含む user_reauth Webhook を送信します。このイベントを処理し、保存済みの old_user.user_id を new_user.user_id に移行してください。(dev-id, reference_id, provider) ごとに有効な接続は常に 1 つだけです。この置き換えが発生するのは reference_id を指定した場合のみです。reference_id が空の場合は古い接続が蓄積するため、reference_id を必ず設定する理由がもう 1 つあります。
• postActivity には device_data と iOS 14 以降が必要です。 ペイロードに device_data がないと、完了したアクティビティの書き込みに失敗します。

判断が必要な事項

これらはお客様自身で決定する事項であり、ドキュメントでは指定していません。慎重に判断してください。

• リクエストするデータ型／権限。 customPermissions が空の場合、デフォルトですべての利用可能な権限が対象になります。対象を絞ると権限の範囲を縮小できますが、バックグラウンド配信カテゴリ（上記）は有効にしておく必要があります。
• HealthKit のプロンプトをすぐに表示するか、後で表示するか。 Terra.instance で requestPermissions: false を設定すると、再訪ユーザーを通知なしで認識でき、ユーザーの明示的な操作に応じてポップアップを表示できます。references/ios.md を参照してください。
• 端末の切り替えへの対応。 2 台目の端末や再インストールによって既存の接続が置き換わり、user_reauth が発生します（上記参照）。任意の端末からの接続を許可して user_reauth 時に user_id を移行するか、initConnection を主要端末 1 台に制限するかを決定してください。
• Android の接続方法として Samsung との直接連携と Health Connect のどちらを選ぶか（および、Samsung とのパートナーシップが承認されるまで Health Connect を使い始めるかどうか）。
• バックフィルの方法。 getDaily／getSleep などの取得関数では、toWebhook: true（送信先にプッシュ）または toWebhook: false（ペイロードをクライアントコールバックに返す）を指定できます。
• バックエンドからクライアントに認証トークンを渡す方法と、reference_id の方式（これはすべての Webhook に含まれる結合キーです）。

プラットフォーム別リファレンス

使用するプラットフォームのファイルをお読みください。

• references/ios.md – TerraiOS をネイティブに（Swiftで）統合する場合にお読みください：機能、info.plist のキー、Terra.instance、プロンプトの遅延表示、setUpBackgroundDelivery、setIgnoredSources、データの書き込み、計画済みワークアウトの WorkoutKit 同期。
• references/android.md – TerraAndroid をネイティブに（Kotlinで）統合する場合にお読みください：build.gradle の座標、minSDK 28、Samsung と Health Connect のセットアップ、ProGuard、マニフェストの intent-filter、startIntent（非推奨で、常に null）。
• references/react-native.md – terra-react を統合する場合にお読みください：インストール、iOS と Android のネイティブ設定、initTerra／initConnection、AppDelegate のバックグラウンド配信用の編集、postActivity（Apple Health のみ）。
• references/flutter.md – terra_flutter_bridge を統合する場合にお読みください：flutter pub、ネイティブ設定、TerraFlutter API、AppDelegate のバックグラウンド配信、ゲッター。

ドキュメント全文：docs.tryterra.co。シグネチャや列挙型がここに記載されていない場合は、モバイル専用ソースからリンクされている SDK リファレンスをご覧ください。ページを取得する前に terra docs ask（または MCP 経由で docs_ask）に質問してください。ドキュメントに基づいて回答し、情報源を引用します。ドキュメントの URL の末尾に .md を追加すると、Markdown 形式で表示できます。