Referência do Web SDK

​

Configuração & debugging

​

init()

window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "ONESIGNAL_APP_ID",
  });
});

​

Parâmetros promptOptions

​

Parâmetros notifyButton

​

Parâmetros welcomeNotification

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.init({
    appId: "YOUR_APP_ID",
    notifyButton: {
      enable: true,
    },
    promptOptions: {
      slidedown: {
        prompts: [{
            type: "smsAndEmail",
            autoPrompt: false,
            text: {
              emailLabel: "Insert Email Address",
              smsLabel: "Insert Phone Number",
              acceptButton: "Submit",
              cancelButton: "No Thanks",
              actionMessage: "Receive the latest news, updates and offers as they happen.",
              updateMessage: "Update your push notification subscription preferences.",
              confirmMessage: "Thank You!",
              positiveUpdateButton: "Save Preferences",
              negativeUpdateButton: "Cancel",
            },
            delay: {
              pageViews: 1,
              timeDelay: 20
            },
          },
          {
            type: "category",
            autoPrompt: true,
            text: {
              actionMessage: "We'd like to show you notifications for the latest news and updates.",
              acceptButton: "Allow",
              cancelButton: "Cancel",

              /* CATEGORY SLIDEDOWN SPECIFIC TEXT */
              negativeUpdateButton: "Cancel",
              positiveUpdateButton: "Save Preferences",
              updateMessage: "Update your push notification subscription preferences.",
            },
            delay: {
              pageViews: 3,
              timeDelay: 20
            },
            categories: [{
                tag: "politics",
                label: "Politics"
              },
              {
                tag: "local_news",
                label: "Local News"
              },
              {
                tag: "world_news",
                label: "World News",
              },
              {
                tag: "culture",
                label: "Culture"
              },
            ]
          }
        ]
      }
    }
  });
});
</script>

​

setLogLevel()

  OneSignal.Debug.setLogLevel("trace");

• 'trace'
• 'debug'
• 'info'
• 'warn'
• 'error'

​

Identidade & propriedades do usuário

​

login(external_id)

• O SDK muda para aquele usuário existente.
  • Você pode ver um 409 Conflict no log de rede ou console do navegador. Isso significa que o External ID já existe no app; é esperado nesse caminho e normalmente não é uma rejeição de promise que você precise tratar.
• O onesignal_id atual é descartado e o onesignal_id existente daquele usuário é carregado.
• O dispositivo atual (Subscription web push) é vinculado ao usuário existente.
• Dados anônimos coletados antes do login não são mesclados e são descartados. Isso inclui tags, dados de sessão, Subscriptions de email/SMS e outras propriedades locais do usuário.

• Um novo usuário é criado usando o onesignal_id atual.
• Todos os dados coletados enquanto o usuário era anônimo são mantidos.
• O dispositivo (Subscription web push) fica vinculado a esse novo usuário.

• O SDK repete automaticamente a solicitação de login em falhas de rede ou erros de servidor.
• Você não precisa implementar sua própria lógica de retry.

• Chame login(external_id) a cada carregamento de página assim que souber o ID do usuário (por exemplo, após o sign-in ou restauração de sessão).
• Chame novamente sempre que o usuário conectado mudar (troca de conta).
• Não chame login antes de ter um identificador de usuário estável e conhecido.

OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.login("external_id");
});

​

logout()

• Remove o external_id da Subscription web push atual. Não remove o external_id de outras Subscriptions.
• 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é que ele seja identificado com o método login.

OneSignalDeferred.push(async function(OneSignal) {
  await OneSignal.logout();
});

​

OneSignal.User.onesignalId

• Após o OneSignal SDK terminar a inicialização
• Após um usuário ser identificado com login(external_id)
• Após trocar de usuário ou restaurar uma sessão

• Rastrear usuários anônimos antes de um External ID ser definido
• Armazenar o OneSignal ID no seu backend para suporte ou debugging
• Correlacionar usuários OneSignal com logs internos
• Exibir o ID para troubleshooting ou QA

const onesignalId = OneSignal.User.onesignalId;

​

OneSignal.User.externalId

  const externalId = OneSignal.User.externalId;

​

addEventListener() User State

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.addEventListener('change', function (event) {
      console.log('change', { event });
    });
  });

​

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

• Defina o external_id com login() antes de adicionar aliases. Aliases adicionados a subscriptions sem external_id não serão sincronizados entre múltiplas subscriptions.
• Veja Aliases para detalhes.

  // Add a single alias
  OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");

  // Add multiple aliases
  OneSignal.User.addAliases({
    ALIAS_LABEL_01: "ALIAS_ID_01",
    ALIAS_LABEL_02: "ALIAS_ID_02",
    ALIAS_LABEL_03: "ALIAS_ID_03",
  });

  // Remove a single alias
  OneSignal.User.removeAlias("ALIAS_LABEL");

  // Remove multiple aliases
  OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02", "ALIAS_LABEL_03"]);

​

getLanguage(), setLanguage()

  // Get the language of the currently logged-in user
  OneSignal.User.getLanguage();

  // Set the language of the currently logged-in user
  OneSignal.User.setLanguage("en");

​

Eventos personalizados

• 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": {
    "device_os": "138",
    "type": "ChromePush",
    "device_model": "MacIntel",
    "sdk": "160500"
  }
}

​

trackEvent()

OneSignalDeferred.push(async function (OneSignal) {
  await OneSignal.init({ appId: "ONESIGNAL_APP_ID" });

  const properties = {
    promo_code: "NEW50",
    membership_details: {
      vip: true,
      products_viewed_count: 15,
    },
  };
  OneSignal.User.trackEvent("started_free_trial", properties);

  // Event name only (no properties)
  OneSignal.User.trackEvent("my_event_name");
});

​

Tags

​

addTag(), addTags()

• Os valores serão substituídos se a chave já existir.
• Exceder o limite de tags do seu plano fará com que as operações falhem silenciosamente.

  // Add a single tag
  OneSignal.User.addTag('tag_key', 'tag_value');

  // Add multiple tags
  OneSignal.User.addTags({
   KEY_01: "VALUE_01",
   KEY_02: "VALUE_02",
   KEY_03: "VALUE_03"
  });

​

removeTag(), removeTags()

  // Delete a single tag
  OneSignal.User.removeTag("KEY");

  OneSignal.User.removeTags(['KEY_01', 'KEY_02', 'KEY_03']);

​

getTags()

  const tags = OneSignal.User.getTags()

​

Privacidade

​

setConsentRequired()

  OneSignal.setConsentRequired(true);

​

setConsentGiven()

• 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, e depois for definido como false, aquela Subscription não receberá mais atualizações. Os dados atuais daquela 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.

  OneSignal.setConsentGiven(true);

​

Subscriptions

​

User.PushSubscription.id

  const subscription_id = OneSignal.User.PushSubscription.id;

​

User.PushSubscription.token

  OneSignal.User.PushSubscription.token;

​

addEventListener() Mudanças de Subscription Push

• O dispositivo recebe um novo token push do Google (FCM) ou da Apple (APNs)
• O OneSignal atribui um subscription ID
• O valor optedIn muda (ex.: chamou optIn() ou optOut())
• O usuário alterna a permissão push nas configurações do navegador ou do SO e depois retorna ao seu site

  function pushSubscriptionChangeListener(event) {
    console.log("event.previous.id", event.previous.id);
    console.log("event.current.id", event.current.id);
    console.log("event.previous.token", event.previous.token);
    console.log("event.current.token", event.current.token);
    console.log("event.previous.optedIn", event.previous.optedIn);
    console.log("event.current.optedIn", event.current.optedIn);
  }

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });

  function pushSubscriptionChangeListener(event) {
    if (!event.current.token || event.previous.token) {
      return;
    }
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      event: "onesignal_push_subscribed",
      onesignal_subscription_id: event.current.id,
    });
  }

  OneSignalDeferred.push(function(OneSignal) {
    OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
  });

​

optOut(), optIn(), optedIn

• optOut(): Define o status de subscription push atual como unsubscribed (mesmo se o usuário tiver um token push válido).
• optIn(): Faz uma das seguintes 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.

  OneSignal.User.PushSubscription.optOut();

  OneSignal.User.PushSubscription.optIn();

  var optedIn = OneSignal.User.PushSubscription.optedIn;

​

addEmail(), removeEmail()

• O endereço de email se torna uma Subscription de email do usuário atual.
• O email pode ser criado ou reatribuído.
• O mesmo endereço de email não pode existir múltiplas vezes no mesmo app OneSignal. Se você vir endereços de email duplicados, verifique suas solicitações REST API e contate o suporte se necessário.

• A Subscription de email é removida do usuário atual.
• O External ID atual é removido da Subscription de email.
• Um novo OneSignal ID é atribuído à Subscription de email.
• Outras Subscriptions (push, SMS, outros emails) permanecem inalteradas.

• Chame login() primeiro, depois chame addEmail(). Caso contrário, o email pode ser anexado a um usuário anônimo.
• Use um endereço de email estável e verificado.
• Siga as Boas práticas de reputação de email.

  OneSignal.User.addEmail("example@email.com");

  OneSignal.User.removeEmail("example@email.com");

​

addSms(), removeSms()

• O número de telefone se torna uma Subscription SMS do usuário atual.
• O número pode ser criado ou reatribuído.
• O mesmo número de telefone não pode existir múltiplas vezes no mesmo app OneSignal. Se você vir números de telefone duplicados, verifique suas solicitações REST API e contate o suporte se necessário.

• A Subscription SMS é removida do usuário atual.
• O External ID atual é removido da Subscription SMS.
• Um novo OneSignal ID é atribuído à Subscription SMS.
• Outras Subscriptions (push, email, outros SMS) permanecem inalteradas.

• Chame login() primeiro, depois chame addSms(). Caso contrário, a Subscription SMS pode ser anexada a um usuário anônimo.
• Sempre valide e normalize números de telefone para o formato E.164 antes de enviar.
• Siga os Requisitos de registro de SMS.

  OneSignal.User.addSms("+15558675309");

  OneSignal.User.removeSms("+15558675309");

​

Prompts Slidedown

• 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 o 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 pela UI, como um clique de botão.

​

promptPush()

• Se estiver usando categorias, chame promptPushCategories() em vez disso.
• Sujeito à lógica de backoff definida pelo OneSignal. Veja Prompts de permissão web para mais detalhes.

  OneSignal.Slidedown.promptPush();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptPush({force: true});

​

promptPushCategories()

• Se não estiver usando categorias, chame promptPush() em vez disso.
• Sujeito à lógica de backoff definida pelo OneSignal. Veja Prompts de permissão web para mais detalhes.

  OneSignal.Slidedown.promptPushCategories();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptPushCategories({force: true});

​

promptSms()

• Sujeito à lógica de backoff definida pelo OneSignal. Veja Prompts de permissão web para mais detalhes.

  OneSignal.Slidedown.promptSms();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptSms({force: true});

​

promptEmail()

• Sujeito à lógica de backoff definida pelo OneSignal. Veja Prompts de permissão web para mais detalhes.

  OneSignal.Slidedown.promptEmail();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptEmail({force: true});

​

promptSmsAndEmail()

• Sujeito à lógica de backoff definida pelo OneSignal. Veja Prompts de permissão web para mais detalhes.

  OneSignal.Slidedown.promptSmsAndEmail();
  // To bypass backoff logic while testing, pass {force: true}
  //OneSignal.Slidedown.promptSmsAndEmail({force: true});

​

addEventListener() Slidedown

  OneSignalDeferred.push(function(OneSignal) {

    OneSignal.Slidedown.addEventListener('slidedownShown', function (event) {
      console.log('slidedownShown', { event });
    });

  });

​

Notificações push

​

requestPermission()

  OneSignal.Notifications.requestPermission();

​

isPushSupported()

  const isSupported = OneSignal.Notifications.isPushSupported();

​

OneSignal.Notifications.permission

• 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.

  let permission = OneSignal.Notifications.permission;

​

addEventListener() Notifications

  function onClick(event) {
    console.log("click", event);
  }

  OneSignal.Notifications.addEventListener("click", onClick);
  OneSignal.Notifications.removeEventListener("click", onClick);

​

permissionChange

  function permissionChangeListener(permission) {
    if (permission) {
      console.log(`permission accepted!`);
    }
  }

  OneSignal.Notifications.addEventListener("permissionChange", permissionChangeListener);

​

permissionPromptDisplay

  function promptListener(event) {
    console.log("permission prompt displayed", event);
  }

  OneSignal.Notifications.addEventListener("permissionPromptDisplay", promptListener);

​

click

  function clickEventListener(event) {
    console.log(`click event: ${event}`);
  }

  OneSignal.Notifications.addEventListener("click", clickEventListener);

​

foregroundWillDisplay

  function foregroundWillDisplayListener(event) {
    console.log("notification will display", event);
  }

  OneSignal.Notifications.addEventListener("foregroundWillDisplay", foregroundWillDisplayListener);

​

dismiss

• Um usuário propositalmente dispensa a notificação sem clicar no corpo da notificação ou nos 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

  function notificationDismissedListener(event) {
    console.log(`dismiss event: ${event}`);
  }

  OneSignal.Notifications.addEventListener("dismiss", notificationDismissedListener);

​

setDefaultUrl()

  OneSignal.Notifications.setDefaultUrl("https://onesignal.com");

​

setDefaultTitle()

  OneSignal.Notifications.setDefaultTitle("Powered by OneSignal!");

​

Outcomes

​

sendOutcome()

  OneSignal.Session.sendOutcome('outcome name', 19.84);

​

sendUniqueOutcome()

  OneSignal.Session.sendUniqueOutcome('outcome name');