App API
AppAPIを使用すると、FormEngineとDMViewのさまざまなメソッドを使ってアプリからシステムメタデータを読み込めます。アプリから特定の情報を取得するためのさまざまなデータキーへのアクセスを提供します。
xlsformでは、以下の構文でpulldata()関数を使用できます：
'app-api'：FormEngineにApp APIからデータを読み込むよう伝えるキーワード。'data-key'：App APIから読み込みたいデータのキー。- データキーが無効またはサポートされていない場合、計算は「n/a」を返します。
App-APIで使用できるサポートされているデータキーは以下の通りです：
osPlatform：現在のOS名（AndroidまたはiOS）とOSバージョンを返します。Webプラットフォームは空の値を返します。
appPlatform：アプリプラットフォーム名rtSurveyを返します。
appVersion：アプリのバージョン名を返します。
getDisplayWidth：デバイスの画面幅をピクセルで返します。
getDisplayHeight：デバイスの画面高さをピクセルで返します。
getScreenSize：デバイスの画面サイズをインチで返します。
projectCode：ユーザーがサインインしているサイトの現在のプロジェクトコードを返します。
projectURL：ユーザーがサインインしているサイトの現在のプロジェクトURLを返します。デフォルト/フォールバック値は空のテキスト（""）です。
startingPoint：フォームを開始するポイントのパスを返します。詳細は「フォームの開始点」を参照してください。
serverTime：サーバーの日時の最良近似値を返します。
user.[attribute]：指定された属性キーに基づく現在のユーザー属性を返します。利用可能な属性キーについては「ユーザー属性」テーブルを参照してください。
現在のユーザー情報を取得するには、pulldata()パラメーターで「user.」と組み合わせた以下の属性キーを使用します。例：user.username、user.emailなど。
| 属性キー | 説明 |
|---|---|
| username | ユーザーのユーザー名 |
| name | ユーザーのフルネーム |
| staffCode | ユーザーのスタッフコード |
| phone | ユーザーの電話番号 |
| ユーザーのメールアドレス | |
| description | ユーザー情報の説明テキスト |
| organization_id | ユーザーが所属する組織ID |
| organization_name | ユーザーが所属する組織名 |
| team_id | ユーザーが所属するチームID |
| supervisor_id | ユーザーの上司のID |
| is_supervisor | ユーザーが監督者の場合は1、そうでない場合は0 |
instancePath：現在のインスタンスフォルダのパスを返します。
appLanguage：アプリの設定で設定された現在のアプリ言語を返します（例：vi、en）。
openArgs.[attribute]：ActionButton（act_fill_form、act_get_instance）から渡されたopen-form-argumentを返します。デフォルト/フォールバック値は空のテキスト（""）です。
primaryAppColor：アプリのプライマリカラーを取得します。
使用例
調査員のユーザー名と組織を保存する
| type | name | label | calculation |
|---|---|---|---|
| calculate | enumerator_name | pulldata('app-api', 'user.name') | |
| calculate | enumerator_org | pulldata('app-api', 'user.organization_name') | |
| calculate | enumerator_email | pulldata('app-api', 'user.email') |
監査目的でnoteラベルに使用する：
note | interviewer_info | 調査員：${enumerator_name} (${enumerator_org})
デバイスと画面情報
| type | name | label | calculation |
|---|---|---|---|
| calculate | device_platform | pulldata('app-api', 'osPlatform') | |
| calculate | app_ver | pulldata('app-api', 'appVersion') | |
| calculate | screen_w | pulldata('app-api', 'getDisplayWidth') |
トラブルシューティングに有用：各送信にどのデバイスバージョンが使用されたかを識別するためにdevice_platformとapp_verをデータと共にエクスポートする。
デバイス時間の代わりにサーバー時間を使用する
デバイスの時計は間違っている場合があります。より信頼性の高いタイムスタンプにはserverTimeを使用する：
| type | name | label | calculation |
|---|---|---|---|
| calculate | server_ts | pulldata('app-api', 'serverTime') |
ユーザーロールに基づいた条件付きロジック
監督者のみのセクションを監督者にのみ表示する：
| type | name | label | relevant |
|---|---|---|---|
| calculate | is_supervisor | pulldata('app-api', 'user.is_supervisor') | |
| begin_group | supervisor_section | 監督者レビュー | ${is_supervisor} = '1' |
| text | supervisor_notes | 監督者メモ | |
| end_group |
アクションボタンから引数を渡す
フォームがカスタム引数を持つact_fill_formアクションボタンから起動される場合：
| type | name | label | calculation |
|---|---|---|---|
| calculate | passed_hh_id | pulldata('app-api', 'openArgs.household_id') | |
| calculate | passed_task | pulldata('app-api', 'openArgs.task_code') |
アクションボタンは一致するキーで引数を渡す必要があります（例：household_id、task_code）。
プロジェクト情報の使用
| type | name | label | calculation |
|---|---|---|---|
| calculate | project | pulldata('app-api', 'projectCode') | |
| calculate | project_url | pulldata('app-api', 'projectURL') |
注意事項
- すべての
pulldata('app-api', ...)呼び出しはフォームが開かれたときに評価され、セッション中に動的に再評価されません（serverTimeとnow()を除く）。 - キーがサポートされていないかデータが利用できない場合、関数は
'n/a'を返します（空の文字列ではない —!= ''ではなく!= 'n/a'でテストする）。 openArgsの値はフォームがアクションボタンから起動された場合のみ利用可能です。それ以外の場合は空の文字列を返します。