Pular para o conteúdo principal

Configuração & debugging

Você pode notar a necessidade de envolver suas chamadas OneSignal com OneSignalDeferred.push(async function() { ... }) Você pode adicionar quantos métodos desejar dentro da function(). O OneSignal SDK é carregado com o atributo defer na sua página. Por exemplo: <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script> Isso significa que o código OneSignal executará após o documento HTML ter sido completamente analisado, prevenindo qualquer bloqueio do site pelo OneSignal SDK. No entanto, isso apresenta um problema para scripts de página que dependem da variável OneSignalDeferred existir. Para resolver isso, quando você adiciona OneSignal ao seu site, ele deve começar com: window.OneSignalDeferred = window.OneSignalDeferred || []; Isso cria uma variável OneSignalDeferred, e se OneSignal já estiver carregado, é então atribuída à instância carregada. Caso contrário, a variável OneSignal equivale a um array vazio - []. Todos os arrays têm uma função .push(), então neste ponto, a variável OneSignalDeferred é simplesmente um array de funções que estamos adicionando a ela. Quando o SDK finalmente carrega, o SDK processa todas as funções adicionadas até agora e redefine .push().

init()

Inicializa o OneSignal SDK. Deve ser chamado na tag <head> uma vez em cada página do seu site. O ONESIGNAL_APP_ID pode ser encontrado em Keys & IDs.
Se você deseja atrasar a inicialização do OneSignal SDK, recomendamos usar nossos métodos de Privacidade.
Opções de init funcionam apenas com Configuração com Código Personalizado. Caso contrário, são configuradas no dashboard OneSignal.

Parâmetros promptOptions

Use promptOptions para localizar ou personalizar os prompts de permissão do usuário. Todos os campos são opcionais.

Parâmetros notifyButton

Configura o Sino de Subscription (botão de notificação) mostrado na página.

Parâmetros welcomeNotification

Personaliza a notificação de boas-vindas enviada após primeira subscription.
Exemplo:

setLogLevel()

Define o logging para imprimir logs adicionais no console. Veja Debugging com Browser DevTools para mais detalhes.
JavaScript
Níveis de log:
  • 'trace'
  • 'debug'
  • 'info'
  • 'warn'
  • 'error'

Identidade & propriedades do usuário

Quando seus usuários se inscrevem para notificações push no seu website, OneSignal cria automaticamente um OneSignal ID (nível de usuário) e um Subscription ID (nível de dispositivo). Você pode associar múltiplas subscriptions (ex: dispositivos, emails, números de telefone) com um único usuário chamando login() com seu identificador de usuário único.
Veja Users e Aliases para mais detalhes.

login(external_id)

Define o contexto do usuário para o external_id fornecido. Garante que todas as Subscriptions e propriedades associadas com este external_id sejam unificadas sob um único onesignal_id. Veja Users para mais detalhes. Comportamentos principais:
  • Se o external_id já existir, o SDK muda para aquele usuário. Dados anônimos coletados antes do login não são mesclados e serão descartados.
  • Se o external_id não existir, o estado local será salvo sob o onesignal_id atual. Quaisquer dados coletados enquanto o usuário era anônimo serão mantidos.
  • SDK retentar automaticamente em falha de rede ou erro de servidor.
Chame este método cada vez que o usuário abrir o site ou dentro do listener de mudança de Subscription para garantir que o External ID esteja definido e a subscription esteja vinculada ao usuário.

logout()

Desvincula o usuário atual da subscription.
  • Remove o external_id da subscription push atual.
  • Redefine o OneSignal ID para um novo usuário anônimo.
  • Quaisquer novos dados (ex: tags, Subscriptions, dados de sessão, etc.) agora serão definidos no novo usuário anônimo até serem identificados com o método login.
Use isto quando um usuário sair do seu app se você quiser definir a subscription para um novo usuário anônimo.
JavaScript

OneSignal.User.onesignalId

Recupera o OneSignal ID do usuário atual salvo localmente no navegador. Pode ser null se chamado antes do estado do usuário ser inicializado. Em vez disso, use User State addObserver() para escutar mudanças de estado do usuário.
JavaScript

OneSignal.User.externalId

Recupera o External ID do usuário atual salvo localmente no navegador. Pode ser null se não definido via método login ou chamado antes do estado do usuário ser inicializado. Em vez disso, use User State addObserver() para escutar mudanças de estado do usuário.
JavaScript

addEventListener() User State

Escuta mudanças no contexto do usuário (ex: login, logout, atribuição de ID).
JavaScript

addAlias(), addAliases(), removeAlias(), removeAliases()

Aliases são identificadores alternativos (como usernames ou IDs de CRM).
  • Defina external_id com login() antes de adicionar aliases. Aliases adicionados a subscriptions sem external_id não sincronizarão em múltiplas subscriptions.
  • Veja Aliases para detalhes.
JavaScript

getLanguage(), setLanguage()

Obtém e/ou sobrescreve o idioma auto-detectado do usuário. Veja Mensagens multi-idioma para uma lista de códigos de idioma disponíveis.
JavaScript

Eventos personalizados

Acione Journeys e ativação de passo Wait Until via evento personalizado.
Eventos personalizados requerem Web SDK 160500+Um usuário deve estar logado para eventos personalizados serem rastreados.
Rastreie e envie um evento personalizado executado pelo usuário atual.
  • name - Obrigatório. O nome do evento como uma string.
  • properties - Opcional. Pares chave-valor para adicionar ao evento. O dicionário ou mapa de properties deve ser serializável em um Objeto JSON válido. Suporta valores aninhados.
O SDK inclui automaticamente dados específicos do app no payload de properties sob a chave reservada os_sdk que estará disponível para consumo. Por exemplo, para direcionar eventos por tipo de subscription, você acessaria os_sdk.type.
json

trackEvent()

JavaScript

Tags

Tags são pares personalizados key : value de dados string que você define em usuários baseado em eventos ou propriedades de usuário. Veja Tags para mais detalhes.

addTag(), addTags()

Define uma única ou múltiplas tags no usuário atual.
  • Valores serão substituídos se a chave já existir.
  • Exceder o limite de tags do seu plano causará falha silenciosa das operações.
JavaScript

removeTag(), removeTags()

Deleta uma única ou múltiplas tags do usuário atual.
JavaScript

getTags()

Retorna a cópia local das tags do usuário. Tags são atualizadas do servidor durante login() ou novas sessões de app.
JavaScript

Privacidade

setConsentRequired()

Impõe consentimento do usuário antes da coleta de dados começar. Deve ser chamado antes de inicializar o SDK. Este método é o mesmo que adicionar requiresUserPrivacyConsent: true ao método init.
JavaScript

setConsentGiven()

Concede ou revoga consentimento do usuário para coleta de dados. Sem consentimento, nenhum dado é enviado para OneSignal e nenhuma subscription é criada.
  • Se setConsentRequired() ou requiresUserPrivacyConsent estiver definido como true, nosso SDK não será totalmente habilitado até setConsentGiven ser chamado com true.
  • Se setConsentGiven estiver definido como true e uma Subscription for criada, então posteriormente for definido como false, aquela Subscription não receberá mais atualizações. Os dados atuais para aquela Subscription permanecem inalterados até setConsentGiven ser definido como true novamente.
  • Se você deseja deletar os dados de User e/ou Subscription, use nossas APIs Delete user ou Delete subscription.
JavaScript

Subscriptions

Veja Subscriptions para mais detalhes.

User.PushSubscription.id

Recupera o Subscription ID push do usuário atual salvo localmente no navegador. Pode retornar null se chamado muito cedo. É recomendado obter estes dados dentro do subscription observer para reagir a mudanças.
JavaScript

User.PushSubscription.token

Retorna o token de subscription push atual. Pode retornar null se chamado muito cedo. É recomendado obter estes dados dentro do subscription observer para reagir a mudanças.
JavaScript

addEventListener() mudanças de subscription push

Use este método para responder a mudanças de subscription push como:
  • O dispositivo recebe um novo token push do Google (FCM) ou Apple (APNs)
  • OneSignal atribui um subscription ID
  • O valor optedIn muda (ex: chamado optIn() ou optOut())
  • O usuário alterna permissão push nas configurações do sistema, então abre o app
Quando isso acontece, o SDK aciona o evento onPushSubscriptionChange. Seu listener recebe um objeto de estado com os valores previous e current para que você possa detectar exatamente o que mudou. Para parar de escutar atualizações, chame o método removeObserver() ou removeEventListener() associado.
JavaScript

optOut(), optIn(), optedIn

Controla o status de subscription (subscribed ou unsubscribed) da Subscription push atual. Use estes métodos para controlar o status de subscription push no seu site. Casos de uso comuns: 1) Prevenir que push seja enviado para usuários que fazem logout. 2) Implementar um centro de preferências de notificação dentro do seu site.
  • optOut(): Define o status de subscription push atual como unsubscribed (mesmo se o usuário tiver um token push válido).
  • optIn(): Faz uma de três ações:
    1. Se a Subscription tiver um token push válido, define o status de subscription push atual como subscribed.
    2. Se a Subscription não tiver um token push válido, tenta exibir o prompt de permissão push.
  • optedIn: Retorna true se o status de subscription push atual for subscribed, caso contrário false. Se o token push for válido mas optOut() foi chamado, isto retornará false.
JavaScript

addEmail(), removeEmail()

Adiciona ou remove uma Subscription de email (endereço de email) para/do usuário atual. Chame addEmail após login() para definir o contexto de usuário correto. Compatível com Identity Verification.
JavaScript

addSms(), removeSms()

Adiciona ou remove uma Subscription SMS (número de telefone) para/do usuário atual. Requer formato E.164. Chame addSms após login() para definir o contexto de usuário correto. Compatível com Identity Verification.
JavaScript

Prompts Slidedown

Exibe os vários prompts slidedown em seus sites. Veja Prompts de permissão web para mais detalhes.
  • Se dispensado, chamadas futuras serão ignoradas por pelo menos três dias. Recusas adicionais aumentarão o tempo necessário a decorrer antes de solicitar o usuário novamente.
  • Para sobrescrever comportamento de back-off, passe {force: true} para o método. No entanto, para fornecer uma boa experiência de usuário, vincule a ação a um evento iniciado por UI como um clique de botão.
Isso não substitui o Prompt Nativo do Navegador necessário para subscription. Você deve obter permissões usando o prompt nativo do navegador.

promptPush()

Exibe o prompt slidedown regular para notificações push.
JavaScript

promptPushCategories()

Exibe o prompt slidedown de categoria, permitindo que usuários atualizem suas tags. Também aciona o prompt de permissão de notificação nativo se o usuário ainda não concedeu permissão.
JavaScript

promptSms()

Exibe o prompt de subscription SMS.
JavaScript

promptEmail()

Exibe o prompt de subscription de email.
JavaScript

promptSmsAndEmail()

Exibe os prompts de subscription SMS e email simultaneamente.
JavaScript

addEventListener() Slidedown

Adiciona um callback para detectar o evento de prompt Slidedown mostrado.
JavaScript

Notificações push

requestPermission()

Solicita permissão de notificações push via prompt nativo do navegador. Sujeito à lógica de backoff definida pelo navegador. Veja Prompts de permissão web para mais detalhes.
JavaScript

isPushSupported()

Retorna true se o navegador atual suportar web push.
JavaScript

OneSignal.Notifications.permission

Retorna um boolean indicando a permissão atual do site para exibir notificações.
  • true: O usuário concedeu permissão para exibir notificações.
  • false: O usuário negou ou ainda não concedeu permissão para exibir notificações.
Esta é apenas a permissão do site, não leva em conta o status optOut do OneSignal ou a existência do Subscription ID e Push Token, veja OneSignal.User.PushSubscription para estes. Para escutar mudanças em permissão, use o evento permissionChange.
JavaScript

addEventListener() notifications

Você pode se conectar ao ciclo de vida da notificação anexando seus manipuladores de evento a um evento de notificação. Chamar addEventListener permite adicionar um número arbitrário de manipuladores de evento para eventos de notificação. Para parar de escutar eventos, chame o método removeEventListener() associado.
JavaScript

permissionChange

Este evento ocorre quando o usuário clica em Permitir ou Bloquear ou dispensa a solicitação de permissão nativa do navegador.
JavaScript

permissionPromptDisplay

Este evento ocorre quando a solicitação de permissão nativa do navegador acabou de ser mostrada.
JavaScript

click

Este evento disparará quando o corpo/título da notificação ou botões de ação forem clicados.
JavaScript

foregroundWillDisplay

Este evento ocorre antes de uma notificação ser exibida. Este evento é disparado na sua página. Se múltiplas abas de navegador estiverem abertas no seu site, este evento será disparado em todas as páginas nas quais OneSignal está ativo.
JavaScript

dismiss

Este evento ocorre quando:
  • Um usuário propositalmente dispensa a notificação sem clicar no corpo da notificação ou botões de ação
  • No Chrome no Android, um usuário dispensa todas as notificações web push (este evento será disparado para cada notificação web push que mostramos)
  • Uma notificação expira por conta própria e desaparece
Este evento não ocorre se um usuário clicar no corpo da notificação ou em um dos botões de ação. Isso é considerado um evento de click de notificação.
JavaScript

setDefaultUrl()

Define a URL padrão para notificações. Se você não definiu uma URL padrão, sua notificação abrirá na raiz do seu site por padrão.
JavaScript
Para definir a URL padrão para notificações, forneça uma URL válida que você deseja que seja lançada quando a notificação for clicada. Esta URL padrão será usada se nenhuma outra URL for especificada ao criar uma notificação. Se você especificar uma URL ao criar uma notificação, a URL padrão será sobrescrita. No caso do Safari, a URL de ícone de notificação padrão será definida como a URL do Site que você especificou nas suas configurações Safari, pois esta função não está disponível.

setDefaultTitle()

Define o título padrão para exibir em notificações.
JavaScript
Se uma notificação for criada com um título, o título especificado sempre sobrescreve este título padrão. O título de uma notificação tem como padrão o título da página que o usuário visitou por último. Se os títulos de suas páginas variarem entre páginas, esta inconsistência pode ser indesejável. Chame isto para padronizar títulos de página através de notificações, desde que um título de notificação não seja especificado.

Outcomes

sendOutcome()

Aciona um outcome que pode ser visualizado no dashboard OneSignal. Aceita um nome de outcome (string, obrigatório) e um valor (number, opcional). Cada vez que o método sendOutcome é invocado com o mesmo nome de outcome passado, a contagem de outcome aumentará, e o valor de outcome será aumentado pelo valor passado (se incluído). Veja Custom Outcomes para mais detalhes.
JavaScript

sendUniqueOutcome()

Aciona um outcome que pode ser visualizado no dashboard OneSignal. Aceita apenas o nome do outcome (string, obrigatório). sendUniqueOutcome aumentará a contagem para aquele outcome apenas uma vez por usuário. Veja Custom Outcomes para mais detalhes.
JavaScript