Install

Get your API key from your project settings at dash.1sygnal.app .

npm (recommended)


npm install onesygnal-web-sdk

The package has a default export only — there are no named exports (init, track, etc. don’t exist as named imports, despite what older material may show).


import oneSygnal from 'onesygnal-web-sdk';
 
oneSygnal.init('YOUR_API_KEY');

This injects a <script> tag pointing at the hosted bundle (https://repo.1sygnal.app/js/1sygnal.js) and queues calls until it loads — see Configuration for what a pre-ready call returns.

Framework setup

The SDK has no framework dependency — it’s the same npm package everywhere. What differs per framework is where you call init(): it has to run once, client-side, after the DOM exists (the loader appends a <script> tag to document.head with no server-side guard, so calling it during server-side rendering throws).

React

Call init() once, on mount, at the root of your app:


import { useEffect } from 'react';
import oneSygnal from 'onesygnal-web-sdk';
 
function App() {
  useEffect(() => {
    oneSygnal.init('YOUR_API_KEY');
  }, []);
 
  return <YourApp />;
}

Next.js

Next.js renders components on the server first, where document doesn’t exist — init() must run in a Client Component, inside an effect, never at module scope or in a Server Component:


'use client';
 
import { useEffect } from 'react';
import oneSygnal from 'onesygnal-web-sdk';
 
export function OneSygnalInit() {
  useEffect(() => {
    oneSygnal.init('YOUR_API_KEY');
  }, []);
 
  return null;
}

Render <OneSygnalInit /> once from your root layout.

Vue


<script setup>
import { onMounted } from 'vue';
import oneSygnal from 'onesygnal-web-sdk';
 
onMounted(() => {
  oneSygnal.init('YOUR_API_KEY');
});
</script>

Call this once, from your root component.

Angular


import { Component, OnInit } from '@angular/core';
import oneSygnal from 'onesygnal-web-sdk';
 
@Component({ selector: 'app-root' })
export class AppComponent implements OnInit {
  ngOnInit() {
    oneSygnal.init('YOUR_API_KEY');
  }
}

If the app uses Angular Universal (SSR), guard this with isPlatformBrowser — the same server-rendering caveat above applies.

Script tag (no npm)

Load the bundle directly and skip the loader package entirely:


<script
  src="https://repo.1sygnal.app/js/1sygnal.js"
  data-api-key="YOUR_API_KEY"
></script>

Auto-init only fires if the script’s src contains the substring 1sygnal and data-api-key is present. See Troubleshooting.

Loading the bundle directly gives you a different API surface than the npm loader — e.g. init() returns Promise<void> here, void on the loader. See API Reference.