API do aplicativo
A AppAPI permite que os usuários carreguem metadados do sistema a partir do aplicativo usando diferentes métodos no FormEngine e DMView. Ela fornece acesso a várias chaves de dados para recuperar informações específicas do aplicativo.
No XLSForm, você pode usar a função pulldata() com a seguinte sintaxe:
'app-api': Esta palavra-chave informa ao FormEngine para carregar os dados da API do aplicativo.'data-key': Esta é a chave dos dados que você quer carregar da API do aplicativo.- Se a chave de dados for inválida ou não suportada, o cálculo retornará “n/a”.
Aqui estão as chaves de dados suportadas que você pode usar com a App-API:
osPlatform: Retorna o nome atual do SO (Android ou iOS) e a versão do SO. Plataformas web retornarão um valor vazio.
appPlatform: Retorna o nome da plataforma do aplicativo, que é rtSurvey.
appVersion: Retorna o nome da versão do aplicativo.
getDisplayWidth: Retorna a largura da tela do dispositivo em pixels.
getDisplayHeight: Retorna a altura da tela do dispositivo em pixels.
getScreenSize: Retorna o tamanho da tela do dispositivo em polegadas.
projectCode: Retorna o código de projeto atual do site em que o usuário está entrando.
projectURL: Retorna a URL do projeto atual do site em que o usuário está entrando. O valor padrão/fallback é um texto vazio ("").
startingPoint: Retorna o caminho do ponto que inicia o formulário. Consulte “Ponto de início do formulário” para mais detalhes.
serverTime: Retorna a melhor aproximação disponível da data e hora no servidor.
user.[attribute]: Retorna os atributos do usuário atual com base na chave de atributo especificada. Consulte a tabela “Atributos do usuário” para chaves de atributo disponíveis.
Combine as chaves de atributo abaixo com “user.” nos parâmetros do pulldata() para recuperar as informações do usuário atual. Por exemplo, use user.username, user.email, etc.
| Chave de atributo | Descrição |
|---|---|
| username | Nome de usuário do usuário |
| name | Nome completo do usuário |
| staffCode | Código de equipe do usuário |
| phone | Número de telefone do usuário |
| Endereço de e-mail do usuário | |
| description | Texto de descrição nas informações do usuário |
| organization_id | ID da organização à qual o usuário pertence |
| organization_name | Nome da organização à qual o usuário pertence |
| team_id | ID da equipe à qual o usuário pertence |
| supervisor_id | ID do supervisor do usuário |
| is_supervisor | 1 se o usuário é supervisor, 0 se não |
instancePath: Retorna o caminho da pasta da instância atual.
appLanguage: Retorna o idioma atual do aplicativo definido nas configurações do aplicativo (por exemplo, vi, en, pt).
openArgs.[attribute]: Retorna o argumento de abertura de formulário passado pelo ActionButton (act_fill_form, act_get_instance). O valor padrão/fallback é um texto vazio ("").
primaryAppColor: Recupera a cor primária do aplicativo.
Exemplos de uso
Armazenar o nome de usuário e a organização do entrevistador
| 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') |
Use-os em rótulos de nota para fins de auditoria:
note | interviewer_info | Entrevistador: ${enumerator_name} (${enumerator_org})
Informações do dispositivo e da tela
| 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') |
Útil para solução de problemas: exporte device_platform e app_ver junto com seus dados para identificar qual versão do dispositivo foi usada para cada envio.
Hora do servidor em vez da hora do dispositivo
Os relógios dos dispositivos podem estar errados. Use serverTime para um registro de data/hora mais confiável:
| type | name | label | calculation |
|---|---|---|---|
| calculate | server_ts | pulldata('app-api', 'serverTime') |
Lógica condicional baseada na função do usuário
Mostre uma seção apenas para supervisores:
| type | name | label | relevant |
|---|---|---|---|
| calculate | is_supervisor | pulldata('app-api', 'user.is_supervisor') | |
| begin_group | supervisor_section | Revisão do supervisor | ${is_supervisor} = '1' |
| text | supervisor_notes | Notas do supervisor | |
| end_group |
Passar argumentos de um botão de ação
Quando o formulário é iniciado a partir de um botão de ação act_fill_form com argumentos personalizados:
| type | name | label | calculation |
|---|---|---|---|
| calculate | passed_hh_id | pulldata('app-api', 'openArgs.household_id') | |
| calculate | passed_task | pulldata('app-api', 'openArgs.task_code') |
O botão de ação deve passar os argumentos com chaves correspondentes (por exemplo, household_id, task_code).
Usando informações do projeto
| type | name | label | calculation |
|---|---|---|---|
| calculate | project | pulldata('app-api', 'projectCode') | |
| calculate | project_url | pulldata('app-api', 'projectURL') |
Notas
- Todas as chamadas
pulldata('app-api', ...)são avaliadas quando o formulário é aberto e não são reavaliadas dinamicamente durante a sessão (excetoserverTimeenow()). - Se uma chave não for suportada ou os dados não estiverem disponíveis, a função retorna
'n/a'(não string vazia — teste com!= 'n/a'em vez de!= ''). - Os valores de
openArgssó estão disponíveis quando o formulário é iniciado a partir de um botão de ação; caso contrário, retornam string vazia.