Capacitor quickstart

Install the Pushctl Capacitor plugin and register an iOS or Android installation.

The plugin supports Capacitor 7 and 8 and exposes the native Pushctl iOS and Android SDKs through one TypeScript API.

1. Install and synchronize

   npm install @pushctl/capacitor
   npx cap sync
   
2. Complete native setup

   Configure Firebase for Android. For iOS, enable the Push Notifications capability and forward both APNs registration callbacks from AppDelegate.swift. See native setup.

3. Initialize

   import { Pushctl } from '@pushctl/capacitor';
   
   await Pushctl.initialize({
     applicationKey: 'push_live_your_client_token',
   });
   
4. Request permission

   const permission = await Pushctl.requestPermission();
   
   if (!permission.granted) {
     // Explain how to enable notifications in system settings.
   }
   
5. Wait for confirmed registration

   const subscription = await Pushctl.waitForRegistration();
   
   if (!subscription.isRegistered) {
     throw new Error('Pushctl is not ready');
   }
   

   This resolves only after APNs or Firebase registration is confirmed by the Pushctl API. It rejects if native registration fails, the API rejects registration, or no native token arrives within 15 seconds.

6. Identify the signed-in user

   await Pushctl.login({ externalUserId: user.id });
   

   login() resolves only after the Pushctl API accepts the association. It rejects if the installation is not registered or the request fails.

7. Handle opens

   const handle = await Pushctl.addListener('notificationOpened', notification => {
     if (notification.actionUrl) router.push(notification.actionUrl);
   });
   

   Call handle.remove() when the listener’s lifecycle ends.

Use a Client token. The application bundle contains values passed from JavaScript to the native plugin.

Migrate from another provider

Keep the existing provider enabled until waitForRegistration() resolves and login() succeeds. Permission alone does not prove that Pushctl has an active installation.