> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/user/pt-br/guide/account/iot-logic/nodes/geofence-functions.md). # Funções de geocerca Use as geocercas que você já tem na Navixy dentro dos fluxos do IoT Logic para agir quando um dispositivo entrar ou sair de uma área, ou registrar em qual área ele está. As funções de geocerca permitem que um fluxo reaja à localização de um dispositivo, usando as geocercas que você já tem no Navixy. Você referencia uma geocerca em vez de descrever uma área com coordenadas, então os limites permanecem os mesmos que você já usa para alertas e relatórios. ## Qual função você precisa | Se você quiser | Use | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Agir sobre uma geocerca específica, quando um dispositivo está dentro dela, entra nela ou sai dela | `inGeofence()`, `enterGeofence()`, `leaveGeofence()`. Veja [Reagir a uma geocerca](#reacting-to-one-geofence) | | Descobrir em qual geocerca um dispositivo está, sem nomear uma com antecedência | `geofenceName()`. Veja [Registrar a geocerca atual](#recording-the-current-geofence) | {% hint style="warning" %} Você deve criar geocercas no Navixy antes de poder referenciá-las em expressões do IoT Logic. Para criar ou gerenciar geocercas, veja [Geocercas](/docs/user/pt-br/guide/tracking/map-tools/geofences.md). {% endhint %} {% hint style="danger" %} **`geofenceName()` é uma opção paga, vendida separadamente.** Ela vem desativada por padrão para todas as contas, e seu provedor de serviço a habilita por conta, mediante solicitação. As outras três funções não são afetadas e não precisam de nenhuma opção extra. Entre em contato com seu provedor de serviço para que ela seja ativada. Veja [Antes de começar](#before-you-start). {% endhint %} ## Reagir a uma geocerca Use essas três funções quando você já souber qual geocerca é relevante. Cada uma responde sim ou não para a maioria dos pacotes de dados que o dispositivo envia, então um fluxo pode enviar esses dados por um ramo ou outro. Em alguns pacotes, uma função não consegue responder e retorna um valor vazio. Veja [Quando uma função de geocerca não fornece resposta](#when-a-geofence-function-gives-no-answer). | Função | Responde sim quando | | ------------------- | ------------------------------------------- | | `inGeofence(id)` | O dispositivo está dentro da geocerca agora | | `enterGeofence(id)` | O dispositivo acabou de entrar na geocerca | | `leaveGeofence(id)` | O dispositivo acabou de sair da geocerca | Você os adiciona à condição de um **Lógica** nó. O `id` é o ID numérico da geocerca em sua conta Navixy, e um seletor o preenche para você, então você raramente o digita manualmente. Veja [Como adicionar uma condição de geocerca](#how-to-add-a-geofence-condition). ### Quando uma função de geocerca não fornece resposta `inGeofence()`, `enterGeofence()`, e `leaveGeofence()` retornam um valor vazio em vez de sim ou não quando não conseguem responder. Uma função não consegue responder nestes casos: * O pacote de dados não contém coordenadas. Uma posição de baixa qualidade ainda é testada, então uma correção fraca de GPS fornece um sim ou não real. * A geocerca foi excluída da sua conta Navixy ou ficou inacessível depois que o fluxo foi salvo. Uma geocerca que já está ausente quando você salva o fluxo é rejeitada no momento da gravação. Um valor vazio interrompe a condição da qual faz parte. Quando a função é a condição inteira, os dados vão para o caminho ELSE. Esse roteamento geralmente é o que você quer. Quando a função é combinada com qualquer outra coisa, o valor vazio pode interromper a condição inteira, inclusive os termos que tinham valores. Para manter o restante da condição funcionando, compare a função com `== true`: ```jexl leaveGeofence(51577 /* Armazém de Austin */) == true || leaveGeofence(85269 /* Canteiro de obras 1 */) == true ``` Para a regra completa, veja [Valores ausentes em expressões](/docs/user/pt-br/guide/account/iot-logic/nodes/missing-values-in-expressions.md). ### Sintaxe {% tabs %} {% tab title="Posição atual" %} Este é o formato que o seletor de geocercas insere automaticamente. O nome da geocerca aparece como comentário para facilitar a leitura, mas não tem efeito na avaliação. ```jexl inGeofence(35229 /* Zona de entrega #4 */) enterGeofence(51577 /* Armazém de Austin */) leaveGeofence(85269 /* Canteiro de obras 1 */) ``` {% endtab %} {% tab title="Posição histórica" %} `inGeofence()` aceita dois parâmetros a mais, então pode testar uma posição anterior em vez da atual: ```jexl inGeofence(35229 /* Zona de entrega #4 */, 1) inGeofence(35229 /* Zona de entrega #4 */, 1, 'valid') inGeofence(35229 /* Zona de entrega #4 */, 'valid') ``` O segundo parâmetro informa de qual pacote de dados tomar a posição, contando de trás para frente a partir do atual. O terceiro informa se os pacotes que não contêm posição devem ser contados. Ambos são opcionais e seguem a mesma convenção da `value()` função. `enterGeofence()` e `leaveGeofence()` recebem o ID da geocerca e nada mais. Ambas comparam a posição atual com a anterior, então não há índice para escolher. Um fluxo que passe um segundo parâmetro para qualquer uma das funções não pode ser salvo, e o erro nomeia a função. Mantenha o índice na faixa de 0 a 11. `inGeofence()` aceita um índice maior, salva sem erro e depois retorna um valor vazio para cada pacote. Não envolva uma função de geocerca dentro de `value()`. O primeiro parâmetro de `value()` é um nome de atributo, não uma expressão, então uma chamada como `value("inGeofence(35229)", 1, 'valid')` procura um atributo com esse nome literal e sempre retorna um valor vazio. Para `value()` detalhes da função, consulte [Expressões e sintaxe da Lógica](/docs/user/pt-br/guide/account/iot-logic/nodes/logic-node/logic-node-expressions-and-syntax.md). {% endtab %} {% endtabs %} ### Como adicionar uma condição de geocerca O campo de expressão no **Lógica** painel de configuração do nó inclui um seletor dedicado de geocerca , separado do autocompletar padrão de [atributos](/docs/user/pt-br/guide/account/iot-logic/nodes/initiate-attribute-node/managing-attributes.md#autofill-attribute-names). Ele lista todas as geocercas definidas na sua conta Navixy, agrupadas por nome e ID. Para adicionar uma função de geocerca à sua expressão: {% stepper %} {% step %} #### Abra a configuração do nó Abra o **Lógica** nó clicando nele na tela. {% endstep %} {% step %} #### Abra o seletor de geocerca No **campo Expressão de condição (JEXL)** clique no ícone do seletor de geocerca para abrir a lista de geocercas.
Geofence picker list example, with all three options (in, enter, leave geofence)
{% endstep %} {% step %} #### Localize e selecione uma geocerca Digite parte do nome da geocerca para filtrar a lista. Cada geocerca aparece três vezes, uma para cada função disponível. Selecione a entrada que combine a geocerca de que você precisa com a função que corresponde à sua condição: * `inGeofence` - use quando você precisar verificar se um dispositivo está atualmente dentro da zona selecionada. * `enterGeofence` - use quando você precisar detectar que um dispositivo se moveu de fora da zona selecionada para dentro dela. * `leaveGeofence` - use quando você precisar detectar que um dispositivo se moveu de dentro da zona selecionada para fora dela. O seletor insere a chamada completa da função na posição do cursor no campo de expressão. {% endstep %} {% step %} #### Combine com outras condições, se necessário Use operadores lógicos para combinar a função de geocerca com outras condições. Consulte [Exemplos de condições](#condition-examples). {% endstep %} {% step %} #### Salve a configuração Clique **Aplicar alterações** para confirmar a configuração do nó. {% endstep %} {% endstepper %} {% hint style="info" %} O seletor de geocerca lista apenas as geocercas que existem na sua conta Navixy no momento em que você abre o nó. Se você adicionar uma nova geocerca depois de abrir o nó, feche-o e abra-o novamente para atualizar a lista. {% endhint %} O seletor insere apenas as três funções baseadas em ID. Para usar `geofenceName()`, digite-o no campo você mesmo. ### Exemplos de condições
Condição única de geocerca Dados da Rota com base em se um dispositivo está atualmente dentro de uma zona de entrega: ```jexl inGeofence(35229 /* Zona de entrega #4 */) ``` * **Caminho THEN**: Os dados de dispositivos dentro da zona fluem para cá. Use este ramo para acionar o processamento específico da zona, como ajustar limites de velocidade ou iniciar um atributo de temporizador de permanência. * **Caminho ELSE**: Os dados de dispositivos fora da zona fluem para cá para processamento padrão.
Detecção de entrada Acione uma ação quando um veículo entrar em um local restrito: ```jexl enterGeofence(85269 /* Construction site 1 */) ``` * **Caminho THEN**: Conecte-se a um **Webhook** nó para notificar a segurança do local, ou a um **Ação** nó para registrar o evento de entrada. * **Caminho ELSE**: Continue o processamento normal dos dados para dispositivos que não entram no local.
Detecção de saída Detecte quando um veículo sair de uma área de serviço autorizada durante o horário comercial: ```jexl leaveGeofence(51577 /* Austin Warehouse */) == true && value('business_hours', 0, 'valid') == true ``` * **Caminho THEN**: Envie um alerta por meio de um **Webhook** nó para um sistema de despacho. * **Caminho ELSE**: Continue o processamento normal.
Combinar várias geocercas Verifique se um dispositivo está dentro de qualquer uma de várias zonas restritas: ```jexl inGeofence(35229 /* Delivery zone #4 */) == true || inGeofence(85269 /* Construction site 1 */) == true ``` Cada função é comparada com `== true`, então um pacote em que uma delas não consegue decidir não interrompe a condição inteira. Sem a comparação, a primeira função que retorna um valor vazio interrompe a condição, e as outras zonas nunca são testadas. Veja [Quando uma função de geocerca não fornece resposta](#when-a-geofence-function-gives-no-answer). * **Caminho THEN**: Aplique regras ou notificações específicas da zona. * **Caminho ELSE**: Processe os dados de dispositivos fora de todas as zonas listadas.
Geocerca combinada com um parâmetro do dispositivo Detecte excesso de velocidade em uma zona urbana específica: ```jexl inGeofence(84762 /* destination1 */) == true && value('speed', 0, 'valid') > 50 ``` * **Caminho THEN**: Registre um excesso de velocidade específico dessa zona, ou envie um alerta direcionado. * **Caminho ELSE**: Continue o processamento padrão para dados em conformidade ou fora da zona.
Comparando com a posição anterior Detecte uma transição de fora para dentro comparando a posição atual com a anterior: ```jexl inGeofence(35229 /* Delivery zone #4 */) == true && inGeofence(35229 /* Delivery zone #4 */, 1, 'valid') == false ``` Esta expressão retorna `true` somente no primeiro pacote após um dispositivo entrar na geocerca. `enterGeofence()` faz a mesma coisa em uma chamada, então use esta forma apenas quando você precisar de um índice diferente do pacote anterior. A segunda chamada é comparada com `== false`, então a expressão é acionada somente quando a posição anterior é conhecida e estava fora da geocerca. Um dispositivo sem uma posição válida anterior não corresponde. Não escreva o segundo termo como `!inGeofence(...)`, o que não produz resultado algum quando não há uma posição anterior para testar.
## Registrar a geocerca atual `geofenceName()` informa em qual geocerca um dispositivo está, em vez de testar uma geocerca que você escolheu previamente. Ele retorna o nome como texto, e você armazena esse texto em um atributo próprio. Uma fórmula cobre todas as geocercas que você tem. Você não monta uma cadeia de verificações por geocerca, e não edita o fluxo toda vez que adiciona uma geocerca. Veja o que o atributo contém para um veículo de entrega que envia relatórios ao longo do dia: | Pacote de dados | `zona atual` | | --------------- | ------------------- | | 08:14 | `Garagem principal` | | 09:02 | (vazio) | | 09:47 | `Site do cliente 3` | Você o cria como um atributo calculado em um **Iniciar Atributo** nó. A partir daí, ele se comporta como qualquer outro atributo calculado: ele aparece em [Analisador de dados](/docs/user/pt-br/guide/account/iot-logic/data-stream-analyzer.md), ele pode ser exibido na plataforma como um sensor personalizado e pode ser encaminhado para um sistema externo. ### Antes de começar **A opção deve estar ativada para a sua conta.** `geofenceName()` é vendido separadamente e vem desativado por padrão para todos. Entre em contato com seu provedor de serviços e peça que ele habilite a função de nome da Geocerca na sua conta. Isso ajuda a citar o nome interno do recurso, `iot_logic_geocerca_search`. Até que seja ativado, um fluxo que usa a função não pode ser salvo. O Nó é marcado com este erro: ``` Função geofenceName() no nó "Resolver zona atual" (#2) não está disponível para sua conta ``` Remova a função do Nó para salvar o fluxo ou aguarde até que seu provedor de serviços ative a opção. **Você também precisa de geocercas para buscar.** * Há pelo menos uma geocerca na sua conta. Veja [Geocercas](/docs/user/pt-br/guide/tracking/map-tools/geofences.md). * Para pesquisar apenas parte das suas geocercas, atribua uma Etiqueta a elas. Veja [Use etiquetas](/docs/user/pt-br/guide/tracking/map-tools/geofences.md#use-tags) e [Etiquetas](/docs/user/pt-br/guide/account/tags.md). ### Adicione o atributo Crie um atributo calculado da maneira usual, como descrito em [Gerenciamento de atributos](/docs/user/pt-br/guide/account/iot-logic/nodes/initiate-attribute-node/managing-attributes.md#creating-attributes), e insira uma das fórmulas abaixo no **Fórmula** campo. Digite o nome da função você mesmo. O autocomplete de atributos não oferece `geofenceName`, e o seletor de geocerca está disponível apenas no **Lógica** nó. ### Fórmulas As duas primeiras formas abrangem a maioria dos casos. A terceira lê uma posição anterior em vez da atual. | Fórmula | O que retorna | | ------------------------------ | -------------------------------------------------------------------------------- | | `geofenceName()` | O nome de qualquer geocerca em que o dispositivo esteja no momento | | `geofenceName('depots')` | O nome de uma geocerca marcada `depots` em que o dispositivo está no momento | | `geofenceName('', 1, 'valid')` | O nome de qualquer geocerca em que o dispositivo estava um pacote de dados antes | Todos os três parâmetros são opcionais: * **A Etiqueta**, primeiro, limita a busca às geocercas que você etiquetou com esse nome. Maiúsculas ou minúsculas não fazem diferença, e uma etiqueta vazia significa todas as geocercas. A etiquetagem é importante quando você tem muitas geocercas e apenas algumas delas são relevantes para este atributo, por exemplo, depósitos, mas não locais de clientes. * **O número do pacote**, em segundo lugar, indica até que ponto voltar na pesquisa: `0` é o pacote que está sendo processado, `1` o anterior a ele, e assim por diante. Omita-o para a posição atual. * **O filtro de posição**, em terceiro lugar, é `'válido'` para ignorar pacotes que não continham posição, ou `'all'` para contá-los. Deixe-o de fora e os pacotes sem posição serão contabilizados. Para conhecer os limites exatos de cada parâmetro, consulte [Função de nome da geocerca](/docs/iot-logic-api/technical-details/geofence-name.md) na documentação da API do IoT Logic. ### O que você recebe de volta O atributo contém o nome da geocerca como texto ou um valor vazio quando não há nome a fornecer. Ele fica vazio quando: * O dispositivo está fora de todas as geocercas pesquisadas. * O pacote de dados não contém posição. * Nenhuma geocerca na sua conta tem a etiqueta que você passou. Um valor vazio aparece igual nos três casos. Em uma fórmula, esse valor vazio é escrito como `null`, que é como o exemplo de roteamento abaixo o testa. Para obter texto legível em vez de um vazio, adicione um fallback com o `?:` operador: ```jexl geofenceName() ?: 'Outside all geofences' ``` Quando uma posição cai dentro de duas geocercas sobrepostas, a função retorna um dos dois nomes. A Navixy não classifica geocercas sobrepostas, e o mesmo nome é retornado enquanto o dispositivo permanecer na sobreposição. ### Exemplos de fórmulas
Nome atual da geocerca como atributo Em um **Iniciar Atributo** nó, crie um atributo chamado `zona atual` com esta fórmula: ```jexl geofenceName() ``` Cada pacote de dados registrado dentro de uma geocerca recebe o nome dessa geocerca. Pacotes registrados fora de todas as geocercas recebem um valor vazio.
Somente as geocercas que você etiquetou Etiquete suas geocercas de garagem com `depots`, depois crie um atributo com esta fórmula: ```jexl geofenceName('depots') ?: 'In transit' ``` Um dispositivo dentro de uma garagem recebe o nome dessa garagem. Um dispositivo em qualquer outro lugar recebe `Em trânsito`, inclusive um dispositivo dentro de uma geocerca que não tem `depots` etiqueta.
Roteamento por área em um nó de Lógica IF/THEN `geofenceName()` também funciona como uma condição, o que é útil quando muitas geocercas compartilham uma regra. Para enviar dados registrados dentro de qualquer geocerca etiquetada como `restricted` pelo caminho THEN, use esta condição: ```jexl geofenceName('restricted') != null ``` * **Caminho THEN**: Dados registrados dentro de uma área restrita. Conecte-o a um **Webhook** nó para alertar um despachador. * **Caminho ELSE**: Todos os outros dados. Compare o resultado com `==` ou `!=` apenas. Os `<`, `>`, `<=`, e `>=` operadores não produzem um resultado útil quando o valor está vazio.
Detectando uma mudança de área Para acionar apenas no pacote em que o dispositivo muda de geocerca, compare o nome atual com o nome na posição anterior: ```jexl geofenceName() != geofenceName('', 1, 'valid') ``` O primeiro parâmetro vazio significa todas as geocercas, e `'válido'` faz com que a comparação ignore pacotes que não continham posição. Sem `'válido'`isso, um pacote sem posição é lido como um nome de geocerca vazio, e a condição relata uma mudança que não ocorreu.
## Perguntas frequentes #### Onde encontro o ID da geocerca? O seletor de geocercas exibe o nome e o ID numérico de cada geocerca na lista. Você também pode encontrar o ID na interface de geocercas do Navixy. Ao selecionar uma geocerca no seletor, o ID é inserido automaticamente na expressão. #### Posso armazenar uma verificação de geocerca em um atributo? Sim. Todas as quatro funções funcionam tanto em uma fórmula de atributo quanto em uma condição de roteamento. `geofenceName()` é a escolha natural, pois fornece texto legível. As outras três fornecem um valor sim ou não, ou um valor vazio quando a posição é desconhecida. Um valor sim ou não geralmente é mais útil para roteamento do que para armazenamento. O seletor de geocercas aparece apenas no **Lógica** Nó, portanto, em uma fórmula de atributo, você mesmo digita a função e o ID da geocerca. #### Por que não consigo salvar um fluxo que usa geofenceName? `geofenceName()` é uma opção paga e fica desativada por padrão. Entre em contato com seu provedor de serviços para habilitá-la em sua conta. Consulte [Antes de começar](#before-you-start). #### O que acontece se a geocerca referenciada for excluída? Se uma geocerca referenciada em uma expressão for excluída da sua conta Navixy, a função não poderá mais responder e retornará um valor vazio. Em um **Lógica** Nó que usa a função isoladamente, os dados fluem pela conexão ELSE. O Nó armazena seu próprio atributo como um valor vazio, e não como `false`. Em uma condição que combina a função com outros termos, o valor vazio pode interromper toda a condição. Em um **Iniciar Atributo** Nó, o atributo não tem valor para esse pacote. Consulte [Valores ausentes em expressões](/docs/user/pt-br/guide/account/iot-logic/nodes/missing-values-in-expressions.md). O fluxo continua em execução, mas você não poderá mais salvá-lo até corrigir a expressão. Uma nova tentativa de salvá-lo falha com `Nó "" (#) contém geozonas inexistentes ou inacessíveis`. Atualize ou remova a expressão para restaurar tanto o roteamento quanto a capacidade de salvar. #### inGeofence avalia a posição atual de GPS do dispositivo? Sim. `inGeofence()` verifica a posição informada no pacote de dados atual em relação aos limites da geocerca. Cada pacote é avaliado independentemente, portanto, o resultado reflete a posição do dispositivo no momento em que esse pacote foi recebido. Um pacote que não contém posição recebe um valor vazio em vez de `true` ou `false`. #### Qual é a diferença entre inGeofence e enterGeofence? `inGeofence()` retorna `true` para cada pacote que informa uma posição dentro da geocerca. `enterGeofence()` retorna `true` somente para o pacote que registra o momento em que o dispositivo entrou na geocerca. Use `inGeofence` quando precisar aplicar lógica a todos os dados de dentro da área. Use `enterGeofence` quando precisar reagir especificamente ao evento de cruzamento do limite. #### Por que meu atributo geofenceName está sempre vazio? Verifique estas causas na seguinte ordem: 1. A opção não está ativada para sua conta. Um fluxo salvo anteriormente continua em execução, e a função retorna um valor vazio para cada pacote. Consulte [Antes de começar](#before-you-start). 2. A etiqueta que você forneceu não está atribuída a nenhuma geocerca. Os nomes das etiquetas devem corresponder a uma etiqueta existente em sua conta. 3. O dispositivo realmente está fora de todas as geocercas pesquisadas. 4. Você tem um número muito grande de geocercas e a fórmula não fornece nenhuma etiqueta. Forneça uma etiqueta para pesquisar um conjunto menor. O limite exato está em [Função de nome da geocerca](/docs/iot-logic-api/technical-details/geofence-name.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://navixy.com/docs/user/pt-br/guide/account/iot-logic/nodes/geofence-functions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.