SDKs

Native SDKs for iOS, Android, and JavaScript/TypeScript. All SDKs handle device registration, push token management, and opt-out/opt-in.

iOS (Swift)

Installation

Add via Swift Package Manager in Xcode → File → Add Package Dependencies, or in Package.swift:

Package.swift
.package(
    url: "https://github.com/VisionLab-de/visionpush-swift",
    from: "1.0.0"
)

Setup in AppDelegate

Enable the Push Notifications capability in Xcode (target → Signing & Capabilities), then initialise the SDK:

Swift
import VisionPush
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        VisionPush.configure(
            apiKey: "vp_live_...",
            appId: "your-app-uuid",
            apiUrl: "https://api.yourdomain.com"
        )
        UNUserNotificationCenter.current()
            .requestAuthorization(options: [.alert, .badge, .sound]) { granted, _ in
            if granted {
                DispatchQueue.main.async { application.registerForRemoteNotifications() }
            }
        }
        return true
    }

    func application(_ application: UIApplication,
                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        VisionPush.shared.registerDevice(
            apnsToken: deviceToken,
            externalId: "user-123"   // optional: your internal user ID
        )
    }
}

User identification

Swift
VisionPush.shared.setExternalId("user-123")  // associate with your user
VisionPush.shared.clearExternalId()            // call on logout

Tags, language, timezone

Swift
VisionPush.shared.setTags(["premium", "beta"])
VisionPush.shared.setLanguage("de")         // ISO 639-1
VisionPush.shared.setTimezone("Europe/Berlin")

Opt out / opt in

Swift
VisionPush.shared.optOut()   // suppress all future pushes
VisionPush.shared.optIn()    // re-enable

In-app messages

Swift
VisionPush.shared.fetchInAppMessage { message in
    guard let msg = message else { return }
    // present msg.title, msg.body, msg.imageUrl, msg.actionUrl
}

Android (Kotlin)

Installation

build.gradle.kts (app)
dependencies {
    implementation("de.visionlab:visionpush-android:1.0.0")
}

settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        maven {
            url = uri("https://maven.pkg.github.com/VisionLab-de/visionpush-android")
        }
    }
}

Firebase setup

VisionPush uses FCM v1. Add google-services.json to app/ and apply the plugin:

build.gradle.kts (project)
plugins {
    id("com.google.gms.google-services") version "4.4.2" apply false
}

build.gradle.kts (app)
plugins {
    id("com.google.gms.google-services")
}

Setup in Application class

Kotlin
import de.visionlab.visionpush.VisionPush

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        VisionPush.configure(
            context = this,
            apiKey  = "vp_live_...",
            appId   = "your-app-uuid",
            apiUrl  = "https://api.yourdomain.com"
        )
    }
}

FirebaseMessagingService

Kotlin
import com.google.firebase.messaging.FirebaseMessagingService
import de.visionlab.visionpush.VisionPush

class MyFirebaseService : FirebaseMessagingService() {

    override fun onNewToken(token: String) {
        VisionPush.shared.registerDevice(
            fcmToken   = token,
            externalId = "user-123"
        )
    }

    override fun onMessageReceived(message: RemoteMessage) {
        // VisionPush handles display automatically
        // Custom data: message.data["screen"]
    }
}

AndroidManifest.xml
<service android:name=".MyFirebaseService"
         android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT"/>
    </intent-filter>
</service>

Notification channels

Android 8.0+ requires notification channels. Create them in the admin panel (Apps → Notification Channels) and sync to the device:

Kotlin
VisionPush.shared.syncNotificationChannels()

User identification and tags

Kotlin
VisionPush.shared.setExternalId("user-123")
VisionPush.shared.setTags(listOf("premium", "beta"))
VisionPush.shared.setLanguage("de")
VisionPush.shared.setTimezone("Europe/Berlin")

VisionPush.shared.optOut()
VisionPush.shared.optIn()

JavaScript / TypeScript

Installation

Shell
npm install @visionpush/sdk
# or
yarn add @visionpush/sdk

Service worker

Web Push requires a service worker. Create public/visionpush-sw.js:

public/visionpush-sw.js
importScripts('https://cdn.jsdelivr.net/npm/@visionpush/sdk/sw.js');

Initialise

TypeScript
import { VisionPush } from '@visionpush/sdk';

const vp = new VisionPush({
  apiKey:            'vp_live_...',
  appId:             'your-app-uuid',
  apiUrl:            'https://api.yourdomain.com',
  vapidPublicKey:    'your-vapid-public-key',  // Apps → Platform Config
  serviceWorkerPath: '/visionpush-sw.js',
});

await vp.init();

Request permission and register

TypeScript
const subscription = await vp.requestPermission({
  externalId: 'user-123',
  language:   navigator.language,
  timezone:   Intl.DateTimeFormat().resolvedOptions().timeZone,
});

if (subscription) console.log('Push notifications enabled');

User identification and tags

TypeScript
vp.setExternalId('user-123');
vp.setTags(['premium', 'beta']);
await vp.optOut();
await vp.optIn();

Notification click handler

visionpush-sw.js
self.addEventListener('notificationclick', event => {
  event.notification.close();
  const data = event.notification.data;
  if (data?.action_url) {
    event.waitUntil(clients.openWindow(data.action_url));
  }
});

React hook example

TypeScript (React)
import { useEffect } from 'react';
import { VisionPush } from '@visionpush/sdk';

const vp = new VisionPush({
  apiKey:            import.meta.env.VITE_VP_API_KEY,
  appId:             import.meta.env.VITE_VP_APP_ID,
  vapidPublicKey:    import.meta.env.VITE_VP_VAPID_KEY,
  serviceWorkerPath: '/visionpush-sw.js',
});

export function usePushNotifications(userId?: string) {
  useEffect(() => {
    vp.init().then(() => { if (userId) vp.setExternalId(userId); });
  }, [userId]);

  return {
    enable:  () => vp.requestPermission({ externalId: userId }),
    disable: () => vp.optOut(),
  };
}

Common patterns

Server-side targeting by user ID

Pass external_id during registration. Then target users by that ID from your backend:

Shell (cURL)
curl -X POST https://api.yourdomain.com/v1/push/send-to-users \
  -H "Authorization: Bearer vp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "app_id":       "uuid",
    "external_ids": ["user-123", "user-456"],
    "name":         "Order shipped",
    "contents": {
      "en": { "title": "Your order shipped!", "body": "Arriving tomorrow." }
    },
    "data": { "order_id": "789", "screen": "order_detail" }
  }'

Localized notifications

Pass content in every supported language. Each device receives its registered language, falling back to "en":

JSON
{
  "contents": {
    "en": { "title": "New message",    "body": "You have a new message."       },
    "de": { "title": "Neue Nachricht", "body": "Sie haben eine neue Nachricht." },
    "fr": { "title": "Nouveau message","body": "Vous avez un nouveau message."  }
  }
}

Deep links via data payload

Include a custom data map in the push request. The SDKs expose it in the notification handler.

JSON
{ "data": { "screen": "product_detail", "product_id": "abc-123" } }

← Previous API Reference Next → Observability