App-API
Die App-API ermöglicht es Benutzern, Systemmetadaten aus der App über verschiedene Methoden in der FormEngine und DMView zu laden. Sie bietet Zugriff auf verschiedene Datenschlüssel zum Abrufen spezifischer Informationen aus der App.
Im XLSForm können Sie die Funktion pulldata() mit der folgenden Syntax verwenden:
'app-api': Dieses Schlüsselwort weist die FormEngine an, die Daten von der App-API zu laden.'data-key': Dies ist der Schlüssel der Daten, die Sie von der App-API laden möchten.- Falls der Datenschlüssel ungültig oder nicht unterstützt wird, gibt die Berechnung “n/a” zurück.
Hier sind die unterstützten Datenschlüssel, die Sie mit der App-API verwenden können:
osPlatform: Gibt den aktuellen OS-Namen (Android oder iOS) und die OS-Version zurück. Web-Plattformen geben einen leeren Wert zurück.
appPlatform: Gibt den Namen der App-Plattform zurück, welcher rtSurvey lautet.
appVersion: Gibt den Versionsnamen der App zurück.
getDisplayWidth: Gibt die Breite des Gerätebildschirms in Pixeln zurück.
getDisplayHeight: Gibt die Höhe des Gerätebildschirms in Pixeln zurück.
getScreenSize: Gibt die Bildschirmgröße des Geräts in Zoll zurück.
projectCode: Gibt den aktuellen Projektcode der Website zurück, bei der der Benutzer angemeldet ist.
projectURL: Gibt die aktuelle Projekt-URL der Website zurück, bei der der Benutzer angemeldet ist. Der Standard-/Fallback-Wert ist ein leerer Text ("").
startingPoint: Gibt den Pfad des Punktes zurück, an dem das Formular startet. Weitere Details finden Sie unter “Formularstartpunkt”.
serverTime: Gibt die bestmögliche Annäherung an Datum und Uhrzeit auf dem Server zurück.
user.[attribute]: Gibt die aktuellen Benutzerattribute basierend auf dem angegebenen Attributschlüssel zurück. Verfügbare Attributschlüssel finden Sie in der Tabelle “Benutzerattribute”.
Kombinieren Sie die nachstehenden Attributschlüssel mit “user.” in den pulldata()-Parametern, um aktuelle Benutzerinformationen abzurufen. Verwenden Sie zum Beispiel user.username, user.email usw.
| Attributschlüssel | Beschreibung |
|---|---|
| username | Benutzername des Benutzers |
| name | Vollständiger Name des Benutzers |
| staffCode | Personalcode des Benutzers |
| phone | Telefonnummer des Benutzers |
| E-Mail-Adresse des Benutzers | |
| description | Beschreibungstext in den Benutzerinfos |
| organization_id | Organisations-ID des Benutzers |
| organization_name | Organisationsname des Benutzers |
| team_id | Team-ID des Benutzers |
| supervisor_id | ID des Vorgesetzten des Benutzers |
| is_supervisor | 1, wenn der Benutzer ein Vorgesetzter ist, sonst 0 |
instancePath: Gibt den Pfad des aktuellen Instanzordners zurück.
appLanguage: Gibt die aktuelle App-Sprache zurück, die in den Einstellungen der App festgelegt ist (z. B. vi, en).
openArgs.[attribute]: Gibt das open-form-argument zurück, das vom ActionButton (act_fill_form, act_get_instance) übergeben wurde. Der Standard-/Fallback-Wert ist ein leerer Text ("").
primaryAppColor: Ruft die primäre Farbe der App ab.
Verwendungsbeispiele
Benutzernamen und Organisation des Interviewers speichern
| 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') |
Diese in Notiz-Beschriftungen für Prüfzwecke verwenden:
note | interviewer_info | Interviewer: ${enumerator_name} (${enumerator_org})
Geräte- und Bildschirminformationen
| 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') |
Nützlich für die Fehlersuche: device_platform und app_ver zusammen mit Ihren Daten exportieren, um zu ermitteln, welche Geräteversion für jede Übermittlung verwendet wurde.
Serverzeit statt Gerätezeit
Geräteuhren können falsch sein. Verwenden Sie serverTime für einen zuverlässigeren Zeitstempel:
| type | name | label | calculation |
|---|---|---|---|
| calculate | server_ts | pulldata('app-api', 'serverTime') |
Bedingte Logik basierend auf der Benutzerrolle
Einen nur für Vorgesetzte sichtbaren Abschnitt anzeigen:
| type | name | label | relevant |
|---|---|---|---|
| calculate | is_supervisor | pulldata('app-api', 'user.is_supervisor') | |
| begin_group | supervisor_section | Vorgesetztenüberprüfung | ${is_supervisor} = '1' |
| text | supervisor_notes | Notizen des Vorgesetzten | |
| end_group |
Argumente von einer Aktionsschaltfläche übergeben
Wenn das Formular von einer act_fill_form-Aktionsschaltfläche mit benutzerdefinierten Argumenten gestartet wird:
| type | name | label | calculation |
|---|---|---|---|
| calculate | passed_hh_id | pulldata('app-api', 'openArgs.household_id') | |
| calculate | passed_task | pulldata('app-api', 'openArgs.task_code') |
Die Aktionsschaltfläche muss die Argumente mit passenden Schlüsseln übergeben (z. B. household_id, task_code).
Projektinformationen verwenden
| type | name | label | calculation |
|---|---|---|---|
| calculate | project | pulldata('app-api', 'projectCode') | |
| calculate | project_url | pulldata('app-api', 'projectURL') |
Hinweise
- Alle
pulldata('app-api', ...)-Aufrufe werden beim Öffnen des Formulars ausgewertet und werden während der Sitzung nicht dynamisch neu ausgewertet (außerserverTimeundnow()). - Wenn ein Schlüssel nicht unterstützt wird oder die Daten nicht verfügbar sind, gibt die Funktion
'n/a'zurück (nicht leer — testen Sie mit!= 'n/a'statt!= ''). openArgs-Werte sind nur verfügbar, wenn das Formular von einer Aktionsschaltfläche gestartet wird; sie geben andernfalls eine leere Zeichenkette zurück.