API Reference

Authentication, SDK method parameters, and the push payload format.

Authentication#

Every request is authenticated with a per-app API key. Send it as a Bearer token:

http

Authorization: Bearer <YOUR_APP_API_KEY>

Client SDKs take the same key as apiKey. A key only works for the app it was generated in. A 401 response means the key is missing, wrong, or belongs to a different app — see Troubleshooting.

Operations#

Register / update a user — initialize() registers the device token and profile, and returns a subscription ID.
Update tags — updateTags() sets key-value tags used for segments.
Post an event — postEvent() records a conversion and attributes it to a campaign.
Delivery and press tracking — sent automatically by the SDK, including from the background handler.

initialize()#

javascript

const subscriptionId = await NotifySphere.initialize({
  applicationUserId: 123,
  type: 'AndroidPush', // or 'IOSPush'
  appId: 'your-notifysphere-app-id',
  apiKey: 'your-api-token',
  tags: { userType: 'customer' },
  debug: __DEV__,
});

Field	Type	Required	Description
`applicationUserId`	`string \| number`	Yes	Your own identifier for the user.
`type`	`'AndroidPush' \| 'IOSPush'`	Yes	Channel for this device.
`appId`	`string`	Yes	notifySphere App ID.
`apiKey`	`string`	Yes	App API key.
`name / email / phone`	`string`	No	Optional profile fields.
`tags`	`Record<string, string>`	No	Optional initial tags.
`debug`	`boolean`	No	Enable verbose SDK logging.

updateTags()#

javascript

await NotifySphere.updateTags({
  applicationUserId: 123,
  type: 'AndroidPush',
  tags: { plan: 'premium' },
});

Field	Type	Required	Description
`applicationUserId`	`string \| number`	Yes	The same ID used in initialize().
`type`	`string`	Yes	Channel type.
`tags`	`Record<string, string>`	Yes	Tags to set or overwrite.

postEvent()#

javascript

await NotifySphere.postEvent({
  event: 'booking',
  nsClick: 'abc123', // optional, from a campaign deep-link
  data: { revenue: 2500, order_id: 'ORD123' },
});

Field	Type	Required	Description
`event`	`string`	Yes	Event name, for example booking.
`nsClick`	`string`	No	Attribution token (`ns_click`) from a campaign deep link.
`data`	`object`	No	Arbitrary event data such as revenue or order ID.

Push payload#

Messages sent through FCM use a mixed payload: a notification block plus a data block.

json

{
  "notification": { "title": "Hello!", "body": "You have a new message." },
  "data": {
    "notification_id": "uuid-here",
    "sound": "default",
    "imageUrl": "https://example.com/image.jpg",
    "channelId": "channel_default"
  },
  "android": { "priority": "high" }
}

Background handler#

Register setBackgroundHandler({ appId, apiKey }) synchronously before registerComponent(). It needs the apiKey too, otherwise delivery calls from a killed app return 401.

React Native SDK guide API Keys Test your integration

Stuck or something unclear? Contact us and we'll help.