Quick Start Guide

<!-- Add to your website -->
<script src="https://sdk.openpushapi.com/v1/sdk.js"></script>
<script>
  OpenPush.init({
    appKey: 'your-app-key-here',
    autoPrompt: true,
    promptDelay: 3000
  });
</script>

curl -X POST https://api.openpushapi.com/v1/notifications \
  -H "Content-Type: application/json" \
  -H "X-App-Key: your-app-key" \
  -H "X-App-Secret: your-app-secret" \
  -d '{
    "title": "Hello World!",
    "body": "Your first push notification from OpenPushAPI.",
    "url": "https://yoursite.com",
    "target_type": "all"
  }'

Response

{
  "notification_id": 12345,
  "status": "queued",
  "total_recipients": 847,
  "is_ab_test": false,
  "message": "Notification queued successfully"
}

curl https://api.openpushapi.com/v1/stats/notifications/12345 \
  -H "X-App-Key: your-app-key" \
  -H "X-App-Secret: your-app-secret"

{
  "title": "New Feature: Dark Mode",
  "body": "We've just launched dark mode. Update your settings to try it.",
  "url": "https://yourapp.com/settings/appearance",
  "icon_url": "https://yourapp.com/icons/feature-icon.png",
  "image_url": "https://yourapp.com/images/dark-mode-preview.jpg",
  "target_type": "tags",
  "target_tags": {
    "plan": "pro"
  },
  "target_platforms": ["web", "android"],
  "actions": [
    { "title": "Try Dark Mode", "url": "https://yourapp.com/settings/appearance" },
    { "title": "Maybe Later" }
  ],
  "ttl_seconds": 86400
}

<!-- Standard (readable) -->
<script src="https://sdk.openpushapi.com/v1/sdk.js"></script>

<!-- Minified (production, ~30% smaller) -->
<script src="https://sdk.openpushapi.com/v1/sdk.min.js"></script>

# Download SDK + Service Worker and place in your web root
curl -O https://sdk.openpushapi.com/v1/sdk.min.js
curl -O https://sdk.openpushapi.com/v1/openpush-sw.js

# Serve openpush-sw.js from https://yourdomain.com/openpush-sw.js

OpenPush.init({
  appKey: 'your-app-key',          // Required
  autoPrompt: false,                // Show permission prompt automatically
  promptDelay: 3000,                // Delay in ms before auto-prompt (if autoPrompt: true)
  serviceWorkerUrl: '/openpush-sw.js', // Custom Service Worker path
  softPrompt: {                     // Optional: show a custom UI before the browser dialog
    title: 'Get notified',
    body: 'Stay up to date with the latest news.',
    acceptText: 'Yes, notify me',
    denyText: 'No thanks',
    icon: '/icon.png',              // Optional icon URL
  },
  topics: ['news', 'deals'],        // Auto-subscribe to these topics on registration
  onSubscribe: function(subscriberId) {
    console.log('Subscribed:', subscriberId);
  },
  onError: function(err) {
    console.error('Push error:', err);
  }
});

// Manually trigger the permission flow (shows softPrompt if configured)
await OpenPush.prompt();

// Set tags for the current subscriber
await OpenPush.setTags({ plan: 'pro', cohort: 'beta-users' });

// Remove specific tag keys
await OpenPush.removeTags(['cohort', 'source']);

// Set external ID (your own user ID)
await OpenPush.setExternalId('user_12345');

// Subscribe to topics
await OpenPush.subscribeToTopics(['breaking-news', 'deals']);

// Unsubscribe from topics
await OpenPush.unsubscribeFromTopics(['deals']);

// Get current subscribed topics
const topics = await OpenPush.getTopics();

// Check if user is subscribed
const subscribed = OpenPush.isSubscribed(); // synchronous, returns boolean

// Get current subscriber ID
const subscriberId = OpenPush.getSubscriberId(); // synchronous, returns string | null

// Unsubscribe the current user (removes from API + browser)
await OpenPush.unsubscribe();

# pubspec.yaml — add as a local path dependency
dependencies:
  openpushapi_flutter:
    path: ./packages/openpushapi_flutter

dependencies:
  firebase_core: ^3.0.0
  firebase_messaging: ^15.0.0

import 'dart:io';
import 'package:flutter/foundation.dart' show kIsWeb;
import 'package:openpushapi_flutter/openpushapi_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // iOS: APNs handled automatically — nothing extra needed
  await OpenPushAPI.init(
    config: const OpenPushConfig(
      appKey: 'YOUR_APP_KEY',
      debug: true, // set false in production
    ),
  );

  // Android: provide FCM token yourself
  if (!kIsWeb && Platform.isAndroid) {
    // Uses firebase_messaging — add it to YOUR pubspec, not required by the SDK
    // final token = await FirebaseMessaging.instance.getToken();
    // if (token != null) {
    //   await OpenPushAPI.registerToken(token, platform: 'android');
    // }
    // FirebaseMessaging.instance.onTokenRefresh.listen((t) {
    //   OpenPushAPI.registerToken(t, platform: 'android');
    // });
  }

  runApp(const MyApp());
}

// Link to your user after login
await OpenPushAPI.setExternalId(currentUser.id);

// Segment by plan and country
await OpenPushAPI.setTags({'plan': 'pro', 'country': 'US'});

// Unsubscribe on logout
await OpenPushAPI.unsubscribe();

// Read the subscriber ID
print(OpenPushAPI.subscriberId);

// Web — register a VAPID push endpoint
if (kIsWeb) {
  // Obtain the push subscription endpoint from the browser Push API
  // using your service worker, then:
  await OpenPushAPI.registerToken(pushEndpointUrl, platform: 'web');
}

curl https://api.openpushapi.com/v1/subscribers \
  -H "X-App-Key: ak_live_xxxxxxxxxxxxx" \
  -H "X-App-Secret: as_live_xxxxxxxxxxxxx"

# Filter by platform
GET /v1/subscribers?platform=web

# Filter by active status
GET /v1/subscribers?is_active=1

# Filter by tag
GET /v1/subscribers?tags[plan]=pro

# Pagination
GET /v1/subscribers?limit=50&offset=100

{
  "title": "Hi {{first_name}}, Flash Sale — 24 hours only!",
  "body": "50% off all Pro plans. Offer ends tonight.",
  "url": "https://yourapp.com/sale",
  "icon_url": "https://yourapp.com/icons/sale.png",
  "image_url": "https://yourapp.com/images/sale-banner.jpg",
  "badge_url": "https://yourapp.com/icons/badge.png",
  "target_type": "segment",
  "target_segment_id": 42,
  "target_platforms": ["web", "android", "ios"],
  "target_countries": ["US", "GB", "DE"],
  "actions": [
    { "title": "Claim Offer", "url": "https://yourapp.com/sale" },
    { "title": "Remind Me Later" }
  ],
  "ttl_seconds": 43200,
  "send_at": "2026-04-24T09:00:00Z",
  "timezone_delivery": true,
  "send_time_optimized": false,
  "is_ab_test": false
}

// Create a segment: Pro users in the US on web
{
  "name": "Pro Web US",
  "rules": {
    "platform": "web",
    "country_code": "US",
    "tags.plan": "pro"
  }
}

curl -X POST https://api.openpushapi.com/v1/track/click \
  -H "Content-Type: application/json" \
  -H "X-App-Key: your-app-key" \
  -d '{
    "notification_id": "12345",
    "subscriber_id": "98765"
  }'

// Flutter — track click when user taps notification
FirebaseMessaging.onMessageOpenedApp.listen((message) {
  final notifId = message.data['opn_notification_id'];
  if (notifId != null) OpenPushAPI.trackClick(notifId);
});

curl -X POST https://api.openpushapi.com/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-App-Key: your-app-key" \
  -H "X-App-Secret: your-app-secret" \
  -d '{
    "url": "https://yourserver.com/hooks/push",
    "events": ["delivered", "clicked", "failed"],
    "is_active": true
  }'

{
  "event": "clicked",
  "notification_id": 12345,
  "subscriber_id": 98765,
  "platform": "android",
  "timestamp": "2026-04-06T10:23:11Z"
}

{
  "error": "Subscriber not found"
}

{
  "title": "Hey {{first_name}}, your {{tags.plan}} trial ends soon!",
  "body": "Upgrade today and keep all your {{tags.plan}} features.",
  "url": "https://yourapp.com/upgrade?ref={{external_id}}",
  "target_type": "all"
}

{
  "title": "New Feature Available",
  "body": "We just launched something you'll love.",
  "url": "https://yourapp.com/new",
  "target_type": "all",
  "is_ab_test": true,
  "ab_split_percent": 50,
  "title_b": "You're going to love this",
  "body_b": "Check out the latest update — it's live now."
}

{
  "title": "Black Friday — US & Canada only",
  "body": "Exclusive deal available in your region.",
  "url": "https://yourapp.com/black-friday",
  "target_type": "all",
  "target_countries": ["US", "CA"]
}

{
  "title": "Weekly digest is ready",
  "body": "Here's what happened this week.",
  "target_type": "all",
  "send_time_optimized": true
}

<!-- Add a target element where the bell should appear -->
<div id="openpush-center"></div>

<!-- Load the widget -->
<script src="https://sdk.openpushapi.com/v1/notification-center.js"></script>
<script>
  OpenPushCenter.init({
    appKey: 'your-app-key',
    subscriberId: currentUser.opnSubscriberId, // your subscriber's ID
    targetSelector: '#openpush-center',        // where to mount the bell
    maxItems: 20,                              // max notifications to show
  });
</script>

# Fetch unread in-app notifications
curl "https://api.openpushapi.com/v1/inapp?subscriber_id=98765&limit=20" \
  -H "X-App-Key: your-app-key"

# Mark all as read
curl -X POST https://api.openpushapi.com/v1/inapp/read-all \
  -H "Content-Type: application/json" \
  -H "X-App-Key: your-app-key" \
  -d '{"subscriber_id": 98765}'

curl -X DELETE https://api.openpushapi.com/v1/subscribers/98765 \
  -H "Content-Type: application/json" \
  -H "X-App-Key: your-app-key" \
  -d '{"reason": "too_many"}'

// Show reason dialog, then unsubscribe
await OpenPush.unsubscribe({ showReasonDialog: true });

// Or unsubscribe with a known reason directly
await OpenPush.unsubscribe({ reason: 'too_many' });

// your-service-worker.js
importScripts('https://sdk.openpushapi.com/v1/openpush-sw.js');

// Your existing SW code below...
self.addEventListener('fetch', (event) => {
  // ...
});

// Android — Register FCM token with OpenPushAPI
FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
    val token = task.result

    // Register with OpenPushAPI
    val client = OkHttpClient()
    val body = JSONObject().apply {
        put("platform", "android")
        put("subscription_token", token)
    }.toString()

    val request = Request.Builder()
        .url("https://api.openpushapi.com/v1/subscribers")
        .addHeader("X-App-Key", "your-app-key")
        .post(body.toRequestBody("application/json".toMediaType()))
        .build()

    client.newCall(request).enqueue(...)
}

// iOS — Register APNs token with OpenPushAPI
func application(_ application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()

    // Register with OpenPushAPI
    var request = URLRequest(url: URL(string: "https://api.openpushapi.com/v1/subscribers")!)
    request.httpMethod = "POST"
    request.setValue("your-app-key", forHTTPHeaderField: "X-App-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = try? JSONSerialization.data(withJSONObject: [
        "platform": "ios",
        "subscription_token": token
    ])

    URLSession.shared.dataTask(with: request).resume()
}