App API
App API позволяет загружать системные метаданные из приложения с помощью различных методов в FormEngine и DMView. Он предоставляет доступ к различным ключам данных для получения конкретной информации из приложения.
В XLSForm можно использовать функцию pulldata() со следующим синтаксисом:
'app-api': это ключевое слово сообщает FormEngine о необходимости загрузить данные из App API.'data-key': это ключ данных, которые нужно загрузить из App API.- Если ключ данных недействителен или не поддерживается, вычисление вернёт “n/a”.
Ниже приведены поддерживаемые ключи данных, которые можно использовать с App API:
osPlatform: возвращает текущее название ОС (Android или iOS) и версию ОС. Веб-платформы вернут пустое значение.
appPlatform: возвращает название платформы приложения, которой является rtSurvey.
appVersion: возвращает название версии приложения.
getDisplayWidth: возвращает ширину экрана устройства в пикселях.
getDisplayHeight: возвращает высоту экрана устройства в пикселях.
getScreenSize: возвращает размер экрана устройства в дюймах.
projectCode: возвращает текущий код проекта сайта, в который входит пользователь.
projectURL: возвращает текущий URL проекта сайта, в который входит пользователь. Значение по умолчанию/резервное значение — пустая строка ("").
startingPoint: возвращает путь к точке запуска формы. Подробности см. в разделе «Точка запуска формы».
serverTime: возвращает наилучшее доступное приближение даты и времени на сервере.
user.[attribute]: возвращает атрибуты текущего пользователя на основе указанного ключа атрибута. Доступные ключи атрибутов см. в таблице «Атрибуты пользователя».
Объедините приведённые ниже ключи атрибутов с “user.” в параметрах pulldata() для получения информации о текущем пользователе. Например, используйте 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). Значение по умолчанию/резервное значение — пустая строка ("").
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 | 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доступны только при запуске формы из кнопки действия; в остальных случаях они возвращают пустую строку.