Configuração & debugging
Você pode notar a necessidade de envolver suas chamadas OneSignal comOneSignalDeferred.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.
| Parameter | Type | Description |
|---|---|---|
appId | String | Obrigatório: Seu OneSignal App ID encontrado em Keys & IDs. |
requiresUserPrivacyConsent | Boolean | Atrasa inicialização do SDK até que o usuário forneça consentimento de privacidade. Deve chamar setConsentGiven() para completar a configuração. |
safari_web_id | String | O Safari Web ID para seu certificado Safari .p12 carregado. Web Quickstart. |
promptOptions | Object | Personaliza os prompts de permissão. Detalhes abaixo. |
notifyButton | Object | Habilita e configura o Sino de Subscription. Detalhes abaixo. |
welcomeNotification | Object | Personaliza ou desabilita a notificação de boas-vindas. Detalhes abaixo. |
persistNotification | Boolean | Chrome (apenas desktop) - true: notificação persiste até ser clicada, false: desaparece após pouco tempo. Firefox/Safari ignoram esta configuração. |
webhooks | Object | Configura callbacks de evento. Veja Webhooks. |
autoResubscribe | Boolean | Recomendado: Reinscreve automaticamente usuários que limpam cache do navegador ou migram para OneSignal. Sobrescreve configuração do dashboard se usado no código. |
notificationClickHandlerMatch | String | "exact" (padrão): foca aba com URL exata correspondente. "origin": foca qualquer aba com o mesmo domínio. |
notificationClickHandlerAction | String | "navigate" (padrão): navega para launchURL. "focus": foca aba existente (usado apenas com correspondência "origin"). |
serviceWorkerParam | Object | Define o scope do service worker. Deve ser diferente do scope de outro service worker se aplicável. Exemplo:{ scope: "/myPath/myCustomScope/" } |
serviceWorkerPath | String | Define a localização do arquivo service worker OneSignal. Exemplo:"myPath/OneSignalSDKWorker.js" |
Parâmetros promptOptions
Use promptOptions para localizar ou personalizar os prompts de permissão do usuário. Todos os campos são opcionais.
| Parameter | Type | Description |
|---|---|---|
slidedown | Object | Contém um array de prompts com opções de configuração. |
prompts | Array of Objects | Um array de configurações de prompt. Exemplo:"slidedown": { "prompts": [{...}, {...}] } |
type | String | Tipos de prompt:
|
autoPrompt | Boolean |
|
delay | Object | Controla quando auto-prompt é mostrado:{ pageViews: 3, timeDelay: 20 } = Mostra após 3ª visualização de página e espera de 20s. |
text | Object | Opções de texto personalizado:
|
categories | Array of Objects | Apenas para type: category. Cada objeto inclui:tag: chave internalabel: nome visível ao usuárioExemplo: [ {tag: "local_news", label: "Local News"} ]. Veja Data Tags. |
Parâmetros notifyButton
Configura o Sino de Subscription (botão de notificação) mostrado na página.
| Parameter | Type | Description |
|---|---|---|
enable | Boolean | Habilita o Sino de Subscription. Desabilitado por padrão. |
displayPredicate | Function | Função personalizada (ou Promise) que retorna true ou false para mostrar/ocultar o Sino. Avaliada uma vez quando mostrado. |
size | String | 'small', 'medium', ou 'large'. Reduz para 'small' após subscription. |
position | String | 'bottom-left' ou 'bottom-right'. |
offset | Object | Offsets CSS em pixels: { bottom: '50px', left: '10px' } |
prenotify | Boolean | Se true, mostra ícone “1 não lido” e texto hover personalizado. |
showCredit | Boolean | Defina como false para ocultar “Powered by OneSignal” no popup. |
text | Object | Texto personalizado para a UI do sino. |
Parâmetros welcomeNotification
Personaliza a notificação de boas-vindas enviada após primeira subscription.
| Parameter | Type | Description |
|---|---|---|
disable | Boolean | Desabilita notificação de boas-vindas. |
message | String | Obrigatório: Mensagem da notificação. Padrão para 'Thanks for subscribing!' se em branco. |
title | String | Título da notificação. Padrão para título do site. Use ' ' (espaço) para remover (não recomendado). |
url | URL | URL opcional para abrir quando o usuário clicar na notificação. Tipicamente não necessário. |
Exemplo:
setLogLevel()
Define o logging para imprimir logs adicionais no console. Veja Debugging com Browser DevTools para mais detalhes.
JavaScript
'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 chamandologin() com seu identificador de usuário único.
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_idjá 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_idnão existir, o estado local será salvo sob oonesignal_idatual. 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_idda 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_idcomlogin()antes de adicionar aliases. Aliases adicionados a subscriptions semexternal_idnã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.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.
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
Data tags
Tags são pares personalizadoskey : value de dados string que você define em usuários baseado em eventos ou propriedades de usuário. Veja Data 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()ourequiresUserPrivacyConsentestiver definido comotrue, nosso SDK não será totalmente habilitado atésetConsentGivenser chamado comtrue. - Se
setConsentGivenestiver definido comotruee uma Subscription for criada, então posteriormente for definido comofalse, aquela Subscription não receberá mais atualizações. Os dados atuais para aquela Subscription permanecem inalterados atésetConsentGivenser definido comotruenovamente. - 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
optedInmuda (ex: chamadooptIn()ouoptOut()) - O usuário alterna permissão push nas configurações do sistema, então abre o app
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:- Se a Subscription tiver um token push válido, define o status de subscription push atual como
subscribed. - Se a Subscription não tiver um token push válido, tenta exibir o prompt de permissão push.
- Se a Subscription tiver um token push válido, define o status de subscription push atual como
optedIn: Retornatruese o status de subscription push atual for subscribed, caso contráriofalse. Se o token push for válido masoptOut()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.
- Se usando categorias, chame
promptPushCategories()em vez disso. - Sujeito à lógica de backoff definida pelo OneSignal. Veja Prompts de permissão web para mais detalhes.
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.
- Se não usando categorias, chame
promptPush()em vez disso. - Sujeito à lógica de backoff definida pelo OneSignal. Veja Prompts de permissão web para mais detalhes.
JavaScript
promptSms()
Exibe o prompt de subscription SMS.
- Sujeito à lógica de backoff definida pelo OneSignal. Veja Prompts de permissão web para mais detalhes.
JavaScript
promptEmail()
Exibe o prompt de subscription de email.
- Sujeito à lógica de backoff definida pelo OneSignal. Veja Prompts de permissão web para mais detalhes.
JavaScript
promptSmsAndEmail()
Exibe os prompts de subscription SMS e email simultaneamente.
- Sujeito à lógica de backoff definida pelo OneSignal. Veja Prompts de permissão web para mais detalhes.
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.
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
setDefaultTitle()
Define o título padrão para exibir em notificações.
JavaScript
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