Push through your own OneSignal

The result: when a player's streak is at risk, they are promoted in a league or a friend nudges them, Orishare sends the push through your OneSignal app, with your OneSignal template or Orishare's rendered copy, and records the outcome in the delivery log. Consent, unsubscribes and blocks set in Orishare still apply. See Notifications.

You need: a OneSignal app with push set up in your mobile or web app, its App ID and a REST API key, and a credential with notifications:write (a person's PAT or a secret key).

1. Link players to OneSignal

Orishare addresses OneSignal by external id: the external_id of the Orishare customer (your own user id). In your app, log the player in to OneSignal with that same id:

// React Native (react-native-onesignal) or web (OneSignal Web SDK)
OneSignal.login(user.id); // the same id you send to Orishare as the customer's external_id

2. Connect OneSignal

const API = 'https://api.orishare.com';
const res = await fetch(`${API}/v1/notification_connectors`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${ORISHARE_SECRET_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'connect-onesignal-1',
  },
  body: JSON.stringify({
    kind: 'onesignal',
    name: 'OneSignal production app',
    credentials: { app_id: ONESIGNAL_APP_ID, api_key: ONESIGNAL_REST_API_KEY },
  }),
});
const connector = await res.json(); // { id: 'ncn_...', status: 'active', credential_hint, settings: { app_id } }

The API key is sealed and never shown again; reads return its last four characters. In a test environment connector sends are simulated: the message is recorded as sent and nothing reaches OneSignal. Real pushes go out from a live environment, so use your production OneSignal app there.

3. Route message types to it

For each event you want as a push, create a message type whose route is the connector (POST /v1/notification_message_types, or the change-set command notification_message_type.create):

{
  "key": "streak_at_risk",
  "routes": [
    {
      "channel": "connector",
      "path": "connector",
      "connector_id": "ncn_...",
      "template": "8f6c1a2e-0000-4000-8000-000000000000"
    }
  ],
  "max_per_day": 1
}

• With template, OneSignal sends that template (its id) and receives the event's variables as data (for this type streak_length and period_ends_at), so your template can use them.
• Without template, Orishare renders the title and body from its templates (or the catalogue copy) in the player's language and sends them as the push heading and content.

Repeat for league_promoted, friend_nudge, friend_high_five, friend_streak_at_risk and any other key from GET /v1/notification_catalog. An existing message type changes its routes with PATCH /v1/notification_message_types/{id} and If-Match.

4. What Orishare still decides

OneSignal owns device subscriptions and its own delivery timing. Orishare still refuses messages to deleted players, social messages to anonymous players, expired messages and, for marketing types, players who unsubscribed or opted out of the type in Orishare (the hosted widget's notification_preferences surface, or PATCH /v1/customer/notification_preferences). Frequency caps and quiet hours are for built-in sending; set OneSignal's own if you need them.

5. Check deliveries

GET /v1/notification_messages?channel=connector shows each message with status and reason: sent (OneSignal accepted it), failed with no_device (no OneSignal subscription has that external id), provider_rejected (check last_error on GET /v1/notification_connectors/{id}) or no_template (no template id and no copy), or suppressed with the policy reason. Fix the key with PATCH /v1/notification_connectors/{id} (credentials), and pause sending with POST /v1/notification_connectors/{id}/disable.