SDK overview
Client (Web, iOS, Android, Flutter and bridges) and server (Node, PHP, Python, Go, Java, .NET, Ruby) SDKs; shared concepts and end-to-end verification.
All client SDKs expose the same conceptual API (almost one-to-one with the legacy provider's v5): initialize → login → User.addTags → Notifications.requestPermission → Session.sendEvent. Server SDKs wrap the entire public REST API as resource × method.
Availability
The installation paths you can use today do not require a package registry; ready-made snippets are on Dashboard → SDK Setup:
- Web script tag:
PushizoSDK.jsandPushizoSDKWorker.jsare served by your API server under/sdk-web/(Web SDK → Script tag). - Google Tag Manager: the same script tag as a Custom HTML tag (the GTM template is also available).
- WordPress: a script tag snippet added to your theme's
functions.php(the WordPress plugin is also available). - Server-side REST API: the
/v1endpoints from any language with cURL or an HTTP client (API reference, Quickstart). - Go:
go get github.com/pushizo/pushizo-go(Go). - iOS (Swift Package Manager):
https://github.com/pushizo/pushizo-ios(iOS).
npm (@pushizo/web, @pushizo/node, @pushizo/react, @pushizo/vue, @pushizo/angular, @pushizo/react-native, @pushizo/capacitor, @pushizo/cli, cordova-plugin-pushizo), Maven Central (com.pushizo:pushizo-java, com.pushizo:pushizo-android, com.pushizo:pushizo-android-hms), NuGet (Pushizo), Packagist (pushizo/pushizo-php), pub.dev (pushizo_flutter), PyPI (pushizo), RubyGems (pushizo), crates.io (pushizo) and OpenUPM (com.pushizo.unity) are published as 0.1.0; CocoaPods Pushizo as 0.1.2. The NuGet Pushizo.Maui release is in preparation.
Client SDKs
| Platform | Package | Guide | Example |
|---|---|---|---|
| Web (browser) | @pushizo/web, PushizoSDK.js (API /sdk-web/) | Web | examples/web-vanilla, examples/web-nextjs |
| React / Next.js | @pushizo/react | React | examples/web-nextjs |
| Vue 3 / 2.7, Nuxt | @pushizo/vue | Vue | — |
| Angular 17+ | @pushizo/angular | Angular | — |
| iOS | Pushizo (SPM / CocoaPods) + PushizoExtension | iOS | examples/ios-swiftui |
| Android | com.pushizo:pushizo-android | Android | examples/android-kotlin |
| Flutter | pushizo_flutter | Flutter | examples/flutter-app |
| React Native | @pushizo/react-native (includes an Expo config plugin) | React Native | examples/react-native |
| Capacitor (Ionic) | @pushizo/capacitor (delegates to @pushizo/web on the web) | Capacitor | examples/ionic-capacitor |
| Cordova | cordova-plugin-pushizo | Cordova | examples/cordova |
| .NET MAUI | Pushizo.Maui | .NET MAUI | examples/maui-app |
| Unity | com.pushizo.unity (UPM) | Unity | sdk/unity/Samples~/Demo (UPM sample) |
| Kotlin Multiplatform | com.pushizo:pushizo-kmp (Android; iOS and Maven release in preparation) | Kotlin Multiplatform | examples/kmp-app |
Bridge SDKs (React Native, Capacitor, Cordova, MAUI, Unity) wrap the native Android/iOS SDKs; the queue, sessions, delivery feedback, in-app rendering and trigger evaluation run on the native side. The web framework packages (@pushizo/react, @pushizo/vue, @pushizo/angular) wrap @pushizo/web: React, Vue, Angular.
Server SDKs
| Language | Package | Guide |
|---|---|---|
| Node.js ≥ 20 | @pushizo/node | Node |
| PHP ≥ 8.1 | pushizo/pushizo-php | PHP |
| Python ≥ 3.9 | pushizo (PyPI) | Python |
| Go ≥ 1.23 | github.com/pushizo/pushizo-go | Go |
| Java ≥ 17 | com.pushizo:pushizo-java | Java |
| .NET 8 | Pushizo (NuGet) | .NET |
| Ruby ≥ 3.0 | pushizo (RubyGems) | Ruby |
| Rust ≥ 1.71 | pushizo (crates.io) | Rust |
The Python, Go, Java, .NET, Ruby and Rust SDKs are generated from api/openapi.yaml (npm run sdk:generate); authentication, retries, idempotency, pagination and webhook signature verification live in a hand-written layer. All of them use the same resource/method names (adapted to each language's conventions).
Shared concepts
- App ID (
app_…): Dashboard → App settings. Client SDKs work with the App ID alone; no secret key is needed. - API key (
hs_live_…): server SDKs only; never embed it in a client. - external_id: your user ID.
login(externalId)links the anonymous device to this user; multiple devices merge into the same user.logout()moves the device to a new anonymous user. - Identity verification: when it is enforced in App settings,
loginis accepted only with anidentity_hash = HMAC-SHA256(sdk_secret, external_id)generated by your server (server SDKs provideidentityHash/identity_hashhelpers). - Privacy consent: while
requiresPrivacyConsentis on, no network calls are made untilsetConsentGiven(true)is called (KVKK (Turkish data protection law)/GDPR). - Offline queue: tags, properties, events, aliases, email/SMS additions and delivery feedback are queued on the device and sent in order, idempotently, once a connection is available.
- Delivery tracking:
receivedis recorded when a push arrives (AndroidonMessageReceived, iOS Notification Service Extension, web service worker) andopened(+button_id) when it is tapped; the timeline appears in Dashboard → Message Tracking. - Email / SMS subscription:
User.addEmail/User.addSmsnormalize the address (ayse@pushizo.com,+905321234567) and create a subscription linked to the device's user. - Preferences:
User.getPreferences()/setPreferences([...])for the message categories defined in the dashboard (user × channel opt-in). - In-app messages:
InAppMessages.addTrigger / setScreen / paused, events viaSession.sendEvent; trigger rules are identical across all SDKs (shared vectors insdk/testdata/messaging-vectors.json). - Regional API URL (data residency, ADR-0032 §4): if
apiUrlis omitted or set to the global root (https://api.pushizo.com), client SDKs learn the regional root (api_url) from the app configuration, store it and send all requests there; a customapiUrlis preserved. On a 421HS_WRONG_CELLresponse for an org in another region, the SDK switches to thedetails.api_urlroot and retries the request once (one redirect per request, no loops). Only validhttpsURLs are accepted (user info, query and fragment are rejected; loopbackhttpis allowed for local development); shared vectors are insdk/testdata/cell-routing-vectors.json. - Notification inbox:
Inbox.list / markRead / markAllRead / archive / unreadCount; messages withadd_to_inbox: true.
End-to-end verification (every platform)
- Enable the relevant channel in the dashboard (Channels → Web Push / Android Push / iOS Push); use the simulation provider if you have no real provider.
- Run the example app and tap Request notification permission.
- Dashboard → Subscriptions: the device registration appears; mark it as a Test device.
- Dashboard → Messages → Send test push. The notification arrives; tapping it opens the app/page.
- Dashboard → Message Tracking:
queued → sent → received → opened.
In local development the API runs at http://localhost:4000; from the Android emulator use http://10.0.2.2:4000, and from a physical device use your machine's LAN IP. Dashboard helpers: Getting Started (/<org>/getting-started), SDK Setup (/<org>/sdk-setup), Test Devices, API Explorer, Logs (Developer menu).
Pushizo Web SDK with Angular
The primary path for Angular is the @pushizo/angular package: providePushizo(options) (standalone) or PushizoModule.forRoot(options) (NgModule) initializes the shared @pushizo/web instance once in the browser at app startup;…
Web SDK
@pushizo/web for browser push (Chrome, Edge, Firefox, Safari 16.4+), email/SMS subscriptions, in-app messages and the notification inbox.