Integrar com outros aplicativos

O ArcGIS Survey123 pode ser integrado com outros aplicativos usando um link do Survey123 ou um esquema de URL personalizado. Ambos os métodos suportam os mesmos parâmetros, mas existem diferenças dependentes da plataforma entre os métodos.

Os links do Survey123 iniciam com https://survey123.arcgis.app e podem ser abertos ou podem abrir outros aplicativos do ArcGIS que suportam vinculação de aplicativo e estão disponíveis no iOS e Android somente. Os aplicativos ArcGIS que podem ser abertos com um link doSurvey123 incluemArcGIS QuickCapture, ArcGIS Collector, ArcGIS Navigator, e Explorer for ArcGIS.

Os links de esquemas da URL personalizados começam com arcgis-survey123:// e podem ser abertos ou podem abrir outros aplicativos do ArcGIS no Android e Windows. Para usar um link de esquema da URL personalizado no iOS , o outro aplicativo deve também ter o Survey123 aprovado nele para permitir a vinculação. Os aplicativos ArcGIS que podem ser abertos com um esquema de URL do Survey123 incluem ArcGIS QuickCapture e Collector for ArcGIS (Classic).

Ao usar um esquema de URL personalizado no Windows, você pode criar e testar seu link e seus parâmetros antes de implantá-lo para os trabalhadores móveis como um esquema de URL personalizado ou um link do Survey123 .

Os links do Survey123 são o método preferido de vinculação.

Parâmetros do aplicativo de campo

Os seguintes parâmetros podem ser usados ​​para personalizar como o aplicativo de campo é aberto:

ParâmetroDescriçãoExemploTipo

center

Centraliza o mapa na latitude, longitude e altitude opcional conhecidas.

center=37.8199,-122.4783,20

Texto

field:fieldname

Preenche perguntas da pesquisa com valores de campo.

field:surname=Klauser

Texto

portalUrl

Especifica a URL para o portal onde o item de pesquisa está hospedado.

portalUrl=https://myorg.arcgis.com

Texto

itemID

Especifica o formulário a ser aberto.

itemID=36ff9e8c13e042a58cfce4ad87f55d19

UUID

download

Baixa automaticamente a pesquisa quando o dispositivo estiver online. O padrão é true.

download=false

Booleano

action

Especifica como a pesquisa é aberta. Os valores suportados são collect (o padrão), edit, view e copy.

action=edit

Texto

folder

Especifica a pasta a ser pesquisada quando o parâmetro filter é utilizado. Os valores suportados são inbox, drafts, outbox, sent, * (todas as pastas).

folder=drafts

Texto

callback

Especifica a URL para retornar quando uma ação de formulário (por exemplo, enviar, mover para rascunhos, cancelar ou sair) for concluída.

callback=https://quickcapture.arcgis.app

URL

callback:status

Especifica o status da pesquisa quando o retorno de chamada é ativado. Os valores suportados para status são cancel, draft, e submit.

callback:draft=https://quickcapture.arcgis.app

Texto

filter

Procura pesquisas existentes no dispositivo.

filter=surname:Klauser

Texto

update

Atualiza a caixa de entrada e tenta enviar pesquisas para a caixa de saída. O padrão é false.

update=false

Booleano

q:queryparameter

Consulta a camada de feição de um registro existente. Ele pode ser usado para recuperar conteúdo que não está no dispositivo.

q:objectIds=12

Texto

Parâmetros do aplicativo da web

Os seguintes parâmetros podem ser usados ​​para personalizar como o aplicativo da web é aberto:

ParâmetroDescriçãoExemploTipo

center

Centraliza o mapa na latitude, longitude e altitude opcional conhecidas.

center=37.8199,-122.4783,20

Texto

field:fieldname

Preenche perguntas da pesquisa com valores de campo.

field:surname=Klauser

Texto

portalUrl

Especifica a URL para o portal onde o item de pesquisa está hospedado.

portalUrl=https://myorg.arcgis.com

Texto

open

Especifica o aplicativo usado para abrir a pesquisa. Os valores válidos são web, que abre a pesquisa no aplicativo da web (o padrão , native que abre a pesquisa no aplicativo de campo se o aplicativo de campo estiver instalado e menu, que abre uma página da web para determinar o aplicativo que abrirá a pesquisa.

open=web

Texto

hide

Oculta elementos da pesquisa no aplicativo da web. Ele pode aceitar vários valores separados por uma vírgula. Os valores válidos são navbar (a barra na parte superior da pesquisa, incluindo opções para entrar, sair e alterar o idioma), header, description, footer e theme. Você também pode usar o parâmetro field:fieldName para ocultar uma pergunta, grupo, página ou repetição específica, fornecendo o nome no lugar de fieldName.

Anotação:

As perguntas nas repetições não podem ser ocultadas individualmente.

hide=header,description,footer,theme

Texto

locale

Muda o idioma da pesquisa. Só funciona se a pesquisa incluir vários idiomas.

locale=zh-cn

Texto

mode

Define o modo de formulário da web. Os valores válidos são edit, que define a pesquisa para editar uma entrada existente em vez de criar uma; view, que abre uma entrada existente no modo somente leitura; e copy, que cria uma pesquisa que é preenchida com o conteúdo da entrda especificada. Ao utilizar este parâmetro, o parâmetro globalId também deve ser fornecido.

mode=edit&globalid=42db492cb06111ea...

Texto

globalId

Especifica o registro da pesquisa que é carregado no formulário. Os valores válidos são os IDs globais para registros de pesquisa existentes. O nome deste parâmetro faz distinção entre letra maiúsculas e minúsculas.

globalId=42db492cb06111ea...

Texto

version

Define a versão do aplicativo da web que será utilizada. O único valor válido é latest, que usa a versão mais recente do aplicativo da web, mesmo se a versão da pesquisa estiver bloqueada.

version=latest

Texto

token

Passa um token válido de uma pesquisa. Ele pode ser usado para permitir que os entrevistados respondam a uma pesquisa que requer uma conta do ArcGIS para acessar sem registrar.

token= E60M4Gsc-h4Q8plqQ...

Texto

autoRefresh

Atualiza a pesquisa após o envio. Especifique o atraso (em segundos) antes que a pesquisa seja atualizada.

autoRefresh=3

Inteiro

encodeUrlParams

Obscurece os parâmetros de URL.

encodeUrlParams=true

Booleano

Anotação:

O parâmetro field:fieldname oferece suporte a perguntas de ponto geográfico, traçado geográfico e formato geográfico no aplicativo da web. Para perguntas de ponto geográfico, especifique latitude, longitude e altitude (opcional) separados por espaços. Para traçado geográfico e formato geográfico, para cada vértice especifique a latitude e longitude separadas por um espaço, com cada par de coordenadas separado por um ponto e vírgula. Este exemplo funcionaria para uma pergunta de formato geográfico:

field:geoshape=-37.842156723211474 144.95942945338243;-37.83554486071995 144.9726235713864;-37.85681405373047 144.98240735651922;-37.85954045531896 144.97715349053766

Link para Survey123 a partir de um navegador da web de desktop

Você pode criar um link para abrir o aplicativo de campo que pode ser embutido em outro aplicativo. O mesmo link também pode ser inserido em um navegador da web para teste. As etapas a seguir descrevem como criar um esquema de URL personalizado e usá-lo em um navegador de desktop:

Anotação:

Depois de criar o link, você pode substituir arcgis-survey123:// com https://survey123.arcgis.app como o link do Survey123 .

  1. Digite arcgis-survey123:// em seu navegador.
    O aplicativo de campo Survey123 abre (ou você é solicitado a abri-lo).
    Anotação:

    Para abrir e baixar uma pesquisa de um portal específico, inclua o parâmetro de URL do portal, por exemplo, arcgis-survey123://?portalUrl=host.domain.com/webadaptor (onde host, domain e webadaptorsão substituídos pelas informações do portal).

  2. Você também pode adicionar uma única referência para uma pesquisa e adicioná-la na URL. Primeiro, identifique o ID do item da pesquisa que deseja abrir. Esta é a string de caracteres que o ArcGIS Online utiliza para identificar exclusivamente sua pesquisa e pode ser localizada na URL do seu item de formulário no ArcGIS Online. Por exemplo, se a URL da sua pesquisa for https://exampleurl.maps.arcgis.com/home/item.html?id=36ff9e8c13e042a58cfce4ad87f55d19, o ID de item do seu formulário será 36ff9e8c13e042a58cfce4ad87f55d19.

  3. Para incluir sua pesquisa na URL que você está construindo, adicione ?itemId= e seu ID do item do seu formulário na URL.
    Sua URL deve parecer semelhante ao seguinte:

    arcgis-survey123://?itemId=36ff9e8c13e042a58cfce4ad87f55d19

    Se você testar sua URL, ela deverá agora abrir o aplicativo de campo Survey123 e abrir sua pesquisa imediatamente.

    Anotação:

    Se ainda não estiver no seu dispositivo, a pesquisa será baixada para ele.

  4. Opcionalmente, você pode incluir algumas respostas pré-determinadas para perguntas.
  5. Inclua uma referência ao campo usando o nome atribuído a ele em XLSForm (não seu rótulo) em sua URL. Por exemplo, para preencher o campo Surname, digite &field:Surname= e o valor. O & atua como um separador de parâmetro e field: se refere ao nome da pergunta a ser preenchida.
    Sua URL deve parecer semelhante ao seguinte:

    arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname=Klauser

    Você pode agora utilizar a URL para abrir o aplicativo de campo Survey123 e sua pesquisa, e preencher a pergunta fornecida com a resposta que você definiu. Você pode preencher múltiplas perguntas em uma URL de pesquisa. Os nomes de campo diferenciam letra maiúscula e letra minúscula.

  6. Opcionalmente, você pode adicionar coordenadas na URL, definindo uma localização para uma pergunta de ponto geográfico na pesquisa.
  7. Digite &center=, e digite as coordenadas. Digite as coordenadas de latitude e longitude em graus decimais, separadas por uma única vírgula. Você pode opcionalmente adicionar altitude em metros de decimais como um terceiro valor, também separado por uma vírgula única.

    Sua URL deve parecer semelhante ao seguinte:

    arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname=Klauser&center=37.8199,-122.4783,20

    Esta URL agora abrirá o aplicativo de campo Survey123 e sua pesquisa escolhida, preencherá uma pergunta de texto e fornecerá uma nova localização padrão para sua pergunta de ponto geográfico.

  8. O conteúdo do campo também pode ser passado para Survey123 a partir de um pop-up em um mapa da web do ArcGIS, permitindo a integração com quaisquer aplicativos da Esri que usam pop-ups em um mapa da web. Este recurso pode ser utilizado para preencher um campo no Survey123 com o conteúdo de um atributo da feição, ao invés de um valor definido, fornecendo o nome do atributo incluído entre chaves.
  9. Selecione Configurar Pop-up para uma camada existente em seu mapa da web. No menu suspenso de visualização, selecione Uma visualização de atributo personalizada, clique em Configurar e insira um link para sua pesquisa.

    Configure o link para o esquema de URL no atributo personalizado.

    Esta URL preencherá o campo Surname com o conteúdo do atributo name da feição selecionada, ao invés de um valor definido.

    arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname={name}

  10. Anotação:

    Por padrão, os valores só podem ser passados ​​para selecionar uma ou várias perguntas em um pop-up em um mapa da web se o nome e o rótulo da escolha correspondente forem idênticos. Se os nomes e rótulos em sua lista de opções forem diferentes, você poderá usar funções DomainCode ou UrlEncode em uma expressão ArcGIS Arcade no pop-up para passar pelo valor desejado.

    Perguntas em repetições não podem ser preenchidas.

Link para Survey123 a partir de outro aplicativo

Você pode criar um link para usar em outros aplicativos para abrir o Survey123 e capturar uma pesquisa. As etapas seguintes descrevem como criar um link do Survey123 e utilizá-lo em um pop-up do Explorer. Este link é inserido no pop-up de um mapa da web em sua organização ArcGIS. Você pode opcionalmente testar o link usando um navegador da web (usando etapas semelhantes às da seção acima) em um dispositivo iOS ou Android; no entanto, o link não funcionará no Windows.

  1. Selecione Configurar Pop-up para uma camada existente em um mapa da web que será visualizado no Explorer.
  2. No menu suspenso de visualização, selecioneuma visualização de atributo personalizado, clique em Configurar, e insira o link ao seu projeto.
  3. Para URL, digite https://survey123.arcgis.app e para Texto do Link, digite Iniciar Survey123. Clique em OK.
    1. Abra seu mapa da web no Explorer em um dispositivo móvel.
    2. Selecione uma feição e clique no link Iniciar Survey123 no pop-up para abrir o Survey123.
  4. Para incluir sua pesquisa na URL que você está construindo, adicione ?itemID= e seu ID do item do seu formulário na URL.
    Sua URL deve parecer semelhante ao seguinte:

    https://survey123.arcgis.app/?itemID=36ff9e8c13e042a58cfce4ad87f55d19

    Se você testar sua URL, ela deverá agora abrir o aplicativo de campo Survey123 e abrir sua pesquisa imediatamente.

    Anotação:

    Se ainda não estiver no seu dispositivo, a pesquisa será baixada para ele.

  5. Opcionalmente, você pode incluir algumas respostas pré-determinadas para perguntas.
  6. Inclua uma referência ao campo usando o nome atribuído a ele em XLSForm (não seu rótulo) em sua URL. Por exemplo, para preencher o campo Surname, digite &field:Surname= e o valor. O & atua como um separador de parâmetro e field: se refere ao nome da pergunta a ser preenchida.
    Sua URL deve parecer semelhante ao seguinte:

    https://survey123.arcgis.app/?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname=Klauser

    Você pode agora utilizar a URL para abrir o aplicativo de campo Survey123 e sua pesquisa, e preencher a pergunta fornecida com a resposta que você definiu. Você pode preencher múltiplas perguntas em uma URL de pesquisa. Os nomes de campo diferenciam letra maiúscula e letra minúscula.

  7. Opcionalmente, você pode adicionar coordenadas na URL, definindo uma localização para uma pergunta de ponto geográfico na pesquisa.
  8. Digite &center=, e digite as coordenadas. Digite as coordenadas de latitude e longitude em graus decimais, separadas por uma única vírgula. Você pode opcionalmente adicionar altitude em metros de decimais como um terceiro valor, também separado por uma vírgula única.

    Sua URL final deve parecer semelhante ao seguinte:

    https://survey123.arcgis.app/?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname=Klauser&center=37.8199,-122.4783,20

    Esta URL completa agora abre o aplicativo de campo Survey123 e sua pesquisa escolhida, preenche uma pergunta de texto e fornece uma nova localização padrão para sua pergunta de ponto geográfico.

Passar parâmetros no aplicativo da web Survey123

O aplicativo da web Survey123 pode aceitar parâmetros no mesmo formato que o aplicativo de campo. A única diferença é que você deve utilizar um ponto de interrogação para separar o ID do item da pesquisa no primeiro parâmetro, ao invés de um & comercial (ainda são utilizados para separar os parâmetros). O seguinte exemplo de URL passa os parâmetros da coordenada e sobrenome para uma pesquisa no aplicativo da web Survey123 :

https://survey123.arcgis.com/share/36ff9e8c13e042a58cfce4ad87f55d19?field:surname=Klauser&center=37.8199,-122.4783

O aplicativo da web Survey123 também suporta uma variedade de parâmetros que o aplicativo de campo Survey123 não. Estes parâmetros estão relacionados à apresentação da pesquisa em um navegador.

Anotação:

Se um valor de parâmetro incluir espaços, sinais de adição (+), ou outros caracteres especiais, esses caracteres devem ser codificados por porcentagem. Para mais informações, consulte Codificar parâmetros da URL.

Passar parâmetros no aplicativo da web Survey123 Connect

O esquema de URL utilizado pelo Survey123 Connect é arcgis-survey123connect://, que permite ao usuário baixar automaticamente e abrir uma pesquisa, pronta para edição.

Este esquema de URL aceita diferentes parâmetros do aplicativo de campo ou aplicativo da web; ele aceita ID do item do formulário e a URL do portal em que o item está armazenado. A seguinte URL de exemplo abre uma pesquisa específica no Survey123 Connect a partir do portal ArcGIS Enterprise fornecido, baixando-o se ele ainda não estiver presente:

arcgis-survey123connect://?portalUrl=https://exampleportal.esri.com/arcgis&itemID=36ff9e8c13e042a58cfce4ad87f55d19

Se a sua pesquisa estiver salva no ArcGIS Online, você precisará fornecer a URL de portal do ArcGIS Online como o seguinte:

arcgis-survey123connect://?portalUrl=https://www.arcgis.com&itemID=36ff9e8c13e042a58cfce4ad87f55d19

Anotação:

Estes parâmetros da URL podem somente ser utilizados para abrir formulários que você é proprietário. Não podem ser utilizados para abrir pesquisas que você tem acesso mas não criou.

Link para outros aplicativos do Survey123

Muitos aplicativos podem ser abertos através de links. Você pode criar uma URL que abre outro aplicativo e o coloca em sua pesquisa. Estes aplicativos também podem aceitar parâmetros personalizados em URLs da mesma maneira do Survey123.

Para iniciar, você precisa adicionar uma pergunta de anotação na sua pesquisa com um rótulo que contém a URL.

Anotação:

Em dispositivos iOS, esquemas de URL diferentes de HTTP e HTTPS devem ser adicionados a uma lista aprovada de esquemas no aplicativo. Os seguintes esquemas de URL são aprovados no Survey123:

  • arcgis-appstudio-player
  • arcgis-quickcapture
  • arcgis-collector
  • arcgis-trek2there
  • arcgis-explorer
  • arcgis-navigator
  • arcgis-workforce
  • comgooglemaps
  • foreflightmobile
  • waze
  • spike-partner

Consulte o seguinte para informações sobre alguns aplicativos da Esri que podem ser abertos por Survey123:

Codificar parâmetros de URL

Embora os parâmetros de URL que não são codificados funcionem em alguns ambientes, é recomendável que você codifique os parâmetros da URL. A codificação substitui os caracteres inválidos pelo sinal de porcentagem (%) seguido por seu equivalente hexadecimal.

Por exemplo, o seguinte é um link do Survey123 que usa um retorno de chamada para retornar a um mapa da web específico no Explorer com parâmetros que não são codificados:

https://survey123.arcgis.app/?itemID=36ff9e8c13e042a58cfce4ad87f55d19?callback=https://explorer.arcgis.app?itemId=867895a71a1840399476fc717e76bb43

A seguinte é a mesma URL com parâmetros codificados:

https://survey123.arcgis.app/?itemID%3D36ff9e8c13e042a58cfce4ad87f55d19%3Fcallback%3Dhttps%3A%2F%2Fexplorer.arcgis.app%3FitemId%3D867895a71a1840399476fc717e76bb43

Uma maneira de criar parâmetros codificados é usar ArcGIS Arcade. A função UrlEncode permite definir uma coleção de pares de valores-chaves que representam cada parâmetro e produzem uma URL com a codificação apropriada.

Um autor de pesquisa também pode desejar ocultar os parâmetros da URL para que dados confidenciais não sejam visíveis na URL. Nesse caso, ao criar uma URL para usar no aplicativo da web, inclua encodeUrlParams=true. Para mais informações, consulte Parâmetros do aplicativo da web.