Zum Inhalt springen
BenutzerhandbücherSupport Demo anfordern Anmelden
Pushwoosh.com

Web Push SDK 3.0

Integration

Anchor link to

Integrationsbeispiel auf GitHub

Holen Sie sich das Pushwoosh Web Push SDK und entpacken Sie es. Sie sollten die folgenden Dateien haben:

Anchor link to
  • pushwoosh-service-worker.js

Platzieren Sie all diese Dateien im Stammverzeichnis Ihrer Website.

Anchor link to

Initialisieren Sie das SDK:

Anchor link to
  1. Binden Sie das SDK von unserem CDN asynchron ein.
<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>
  1. Initialisieren Sie das Web Push SDK und stellen Sie sicher, dass die Initialisierung in die Warteschlange gestellt wird, bis das SDK vollständig geladen ist.
<script type="text/javascript">
var Pushwoosh = Pushwoosh || [];
Pushwoosh.push(['init', {
    logLevel: 'info', // possible values: error, info, debug
    applicationCode: 'XXXXX-XXXXX', // you application code from Pushwoosh Control Panel
    apiToken: 'XXXXXXX', //  Device API Token
    safariWebsitePushID: 'web.com.example.domain', //  unique reverse-domain string, obtained in you Apple Developer Portal. Only needed if you send push notifications to Safari browser
    defaultNotificationTitle: 'Pushwoosh', // sets a default title for push notifications
    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // URL to custom custom notification image
    autoSubscribe: false, // or true. If true, prompts a user to subscribe for pushes upon SDK initialization
    subscribeWidget: {
      enable: true
    },
    userId: 'user_id', // optional, set custom user ID
    tags: {
        'Name': 'John Smith'     // optional, set custom Tags
    }
}]);
</script>

Web-Popups

Anchor link to

Fügen Sie webPopups zu Ihrem init-Objekt hinzu, um Web-Popup-Kampagnen auf Ihrer Website zu aktivieren.

webPopups: {
  enable: true,
},

Web-Popup-Kampagnen zeigen Overlays an, die Sie im Control Panel konfigurieren, wie z. B. Werbeaktionen, Ankündigungen oder Formulare zur Lead-Erfassung. Im Gegensatz zum benutzerdefinierten Anmelde-Popup (subscribePopup), das nur die Web-Push-Anmeldung behandelt, können Web-Popup-Kampagnen jeden von Ihnen konfigurierten Inhalt anzeigen. Informationen zur Einrichtung im Control Panel finden Sie unter Grundlegendes zu Web-Popups.

Schaltfläche für die Push-Anmeldung

Anchor link to

Um Ihre Benutzer zur Anmeldung für Push-Benachrichtigungen aufzufordern, empfehlen wir die Implementierung einer Schaltfläche für die Push-Anmeldung auf Ihrer Website. Verbessern Sie die Benutzererfahrung und gewinnen Sie mehr Abonnenten!

Konfiguration

Anchor link to

Um die Implementierung von Push-Benachrichtigungen in Ihre Website abzuschließen, müssen Sie die Web-Plattformen in Ihrem Pushwoosh Control Panel gemäß unseren Schritt-für-Schritt-Anleitungen konfigurieren:

Service Worker in einem anderen Geltungsbereich registrieren

Anchor link to

Manchmal können Sie die Service-Worker-Datei nicht im Stammverzeichnis einer Website, sondern in einem Unterverzeichnis platzieren.

In diesem Fall ändern Sie die Konfiguration (Schritt 4.3), indem Sie einen Parameter hinzufügen

serviceWorkerUrl: “/push-notifications/pushwoosh-service-worker.js”

wobei /push-notifications/pushwoosh-service-worker.js der Pfad zur Datei pushwoosh-service-worker.js ist.

Event-Handler

Anchor link to

Im Pushwoosh Web SDK 3.0 können Sie bestimmte Ereignisse abonnieren, um sie zu verfolgen**,** oder sich von Ereignissen abmelden, wenn Sie sie nicht mehr verfolgen müssen.

Um das Laden des Web SDK 3.0 zu verfolgen, lösen Sie das onLoad-Ereignis wie folgt aus:

// Load Event
Pushwoosh.push(['onLoad', (api) => {
  console.log('Pushwoosh load!');
}]);

Um die korrekte Initialisierung des Web SDK zu verfolgen, lösen Sie das onReady-Ereignis aus:

// Ready Event
Pushwoosh.push((api) => {
  console.log('Pushwoosh ready!');
});

Um sich für SDK-Ereignisse an- oder abzumelden, verwenden Sie die Handler nach dem Laden des SDK:

Pushwoosh.push(['onLoad', (api) => {
  function onEventNameHandler() {
    console.log('Triggered event: event-name!');
  }


  // To subscribe to an event:
  Pushwoosh.addEventHandler('event-name', onEventNameHandler)


  // To unsubscribe from an event:
  Pushwoosh.removeEventHandler('event-name', onEventNameHandler)
}]);

SDK-Ereignisse

Anchor link to

Subscribe-Ereignis

Anchor link to

Wird ausgeführt, nachdem ein Benutzer dem Empfang von Push-Benachrichtigungen zugestimmt hat.

Pushwoosh.push(['onLoad', (api) => {
  Pushwoosh.addEventHandler('subscribe', (payload) => {
    console.log('Triggered event: subscribe');
  });
}]);

Unsubscribe-Ereignis

Anchor link to

Wird ausgeführt, nachdem ein Gerät von Benachrichtigungen abgemeldet wurde.

Pushwoosh.push(['onLoad', (api) => {
  Pushwoosh.addEventHandler('unsubscribe', (payload) => {
    console.log('Triggered event: unsubscribe');
  });
}]);

Ereignisse des Anmelde-Widgets

Anchor link to

Verfolgen Sie die Anzeige eines Anmelde-Widgets.

Pushwoosh.push(['onLoad', (api) => {
  // Executed on displaying of the Subscription Prompt widget
  Pushwoosh.addEventHandler('show-subscription-widget', (payload) => {
    console.log('Triggered event: show-subscription-widget');
  });


  // Executed on hiding of the Subscription Prompt widget
  Pushwoosh.addEventHandler('hide-subscription-widget', (payload) => {
    console.log('Triggered event: hide-subscription-widget');
  });
}]);

Ereignisse des Benachrichtigungs-Berechtigungsdialogs

Anchor link to

Verfolgen Sie die Anzeige des nativen Anmeldedialogs.

Pushwoosh.push(['onLoad', function (api) {
  // Executed on permission dialog displaying
  Pushwoosh.addEventHandler('show-notification-permission-dialog', (payload) => {
    console.log('Triggered event: show-notification-permission-dialog');
  });


  // Executed on hiding the permission dialog with one of three possible statuses:
  // 1. default - the dialog is closed
  // 2. granted - permission is granted
  // 3. denied - permission is denied
  Pushwoosh.addEventHandler('hide-notification-permission-dialog', (payload) => {
    console.log('Triggered event: hide-notification-permission-dialog', payload.permission);
  });
}]);

Permission-Ereignisse

Anchor link to

Überprüfen Sie den Status der Berechtigung für Push-Benachrichtigungen bei der SDK-Initialisierung; verfolgen Sie die Aktualisierung dieses Status, wann immer sie stattfindet.

Pushwoosh.push(['onLoad', (api) => {
  // Executed during the SDK initialization if 'autoSubscribe: false' or/and if a user ignores a push notification prompt.
  Pushwoosh.addEventHandler('permission-default', (payload) => {
    console.log('Triggered event: permission-default');
  });


  // Executed during the SDK initialization if notifications are blocked or once a user blocks push notifications.
  Pushwoosh.addEventHandler('permission-denied', (payload) => {
    console.log('Triggered event: permission-denied');
  });


  // Executed during the SDK initialization if notifications are allowed or once a user allows push notifications.
  Pushwoosh.addEventHandler('permission-granted', (payload) => {
    console.log('Triggered event: permission-granted');
  });
}]);

Receive-Push-Ereignis

Anchor link to

Verfolgen Sie die Zustellung von Pushes an ein Gerät.

Pushwoosh.push(['onLoad', (api) => {
  // Executed when a push notification is displayed.
  Pushwoosh.addEventHandler('receive-push', (payload) => {
    console.log('Triggered event: receive-push', payload.notification);
  });
}]);

Benachrichtigungs-Ereignisse

Anchor link to

Verfolgen Sie, ob eine Push-Benachrichtigung von einem Benutzer geöffnet oder geschlossen wird.

Pushwoosh.push(['onLoad', (api) => {
  // Executed when a user clicks on notification.
  Pushwoosh.addEventHandler('open-notification', (payload) => {
    console.log('Triggered event: open-notification', payload.notification);
  });


  // Executed when a user closes a push notification.
  Pushwoosh.addEventHandler('hide-notification', (payload) => {
    console.log('Triggered event: hide-notification', payload.notification);
  });
}]);

Inbox-Ereignisse

Anchor link to

Verfolgen Sie an die Inbox gesendete Benachrichtigungen.

Pushwoosh.push(['onLoad', (api) => {
  // Executed by ServiceWorker after the Inbox Message is received and saved to indexedDB.
  Pushwoosh.addEventHandler('receive-inbox-message', (payload) => {
    console.log('Triggered event: receive-inbox-message', payload.message);
  });


  // Executed after the Inbox is updated automatically while the page is loading.
  Pushwoosh.addEventHandler('update-inbox-messages', (payload) => {
    console.log('Triggered event: receive-inbox-message', payload.messages);
  });
}]);

Ereignisse des benutzerdefinierten Anmelde-Popups

Anchor link to

Details zur Behandlung von Ereignissen des benutzerdefinierten Anmelde-Popups finden Sie im Leitfaden zu Ereignissen des benutzerdefinierten Anmelde-Popups.

API

Anchor link to

Nachdem das Web Push SDK initialisiert wurde, können Sie die folgenden Aufrufe an die Pushwoosh-API tätigen. Alle Methoden geben Promise-Objekte zurück.

Pushwoosh.push((api) => {
  // Set tags for a user
  api.setTags({
    'Tag Name 1': 'value1',
    'Tag Name 2': 'value2'
  });


  // Get tags for a user from server
  api.getTags();


  // Register user ID
  api.registerUser('user123');


    // Register user email
  api.registerEmail('user@example.com');


  // Register SMS number
  api.registerSmsNumber('+15551234567');


  // Register WhatsApp number
  api.registerWhatsappNumber('+1234567890');


  // Post an Event
  api.postEvent('myEventName', {attributeName: 'attributeValue'});


  //Unregister from notifications
  api.unregisterDevice();


  // Set the device language (overrides the value in the "Language" Tag)
  api.setLanguage('es');


  // Alternatively Multi-register user with devices and channels
  api.multiRegisterDevice({
    user_id: 'user123',
    email: 'user@example.com',
    sms_phone_number: '+1234567890',
    tags: {
      'UserType': { operation: TTagOperationSet, value: 'Premium' },
      'Interests': { operation: TTagOperationAppend, values: ['sports', 'technology'] }
    }
  });
});

multiRegisterDevice

Anchor link to

Erweiterte Registrierungsmethode, die es ermöglicht, ein Benutzerprofil mit mehreren Geräten und Nachrichtenkanälen in einem einzigen API-Aufruf zu registrieren. Diese Methode ist besonders nützlich für plattformübergreifende Anwendungen oder bei der Implementierung von Omnichannel-Messaging-Strategien.

Pushwoosh.push((api) => {
  api.multiRegisterDevice({
    user_id: 'user123',              // Optional: User identifier
    email: 'user@example.com',       // Optional: Email for email messaging
    sms_phone_number: '+1234567890', // Optional: SMS phone number (E.164 format)
    whatsapp_phone_number: '+1234567890', // Optional: WhatsApp number (E.164 format)
    kakao_phone_number: '+1234567890',    // Optional: KakaoTalk number (E.164 format)
    language: 'en',                  // Optional: Language code (ISO 639-1)
    timezone: 'America/New_York',    // Optional: Timezone identifier
    city: 'New York',               // Optional: City for targeting
    country: 'US',                  // Optional: Country for targeting
    state: 'NY',                    // Optional: State for targeting
    tags: {                         // Optional: Tag values with operations
      'UserType': {
        operation: TTagOperationSet,     // Set tag value (0)
        value: 'Premium'
      },
      'Interests': {
        operation: TTagOperationAppend,  // Append to tag value (1)
        values: ['sports', 'technology']
      },
      'LoginCount': {
        operation: TTagOperationIncrement, // Increment tag value (3)
        value: '1'
      }
    },
    push_devices: [                 // Optional: Array of push devices
      {
        hwid: 'web-device-456',
        platform: TPlatformChrome, // Chrome platform (11)
        push_token: 'fcm-token-here',
        app_version: '2.1.0',
        platformData: {
          public_key: 'web-push-public-key',
          auth_token: 'web-push-auth-token',
          browser: 'chrome'
        }
      }
    ]
  })
  .then((response) => {
    console.log('Multi-registration successful:', response);
  })
  .catch((error) => {
    console.error('Multi-registration failed:', error);
  });
});

Plattformtypen:

  • TPlatformSafari (10): Safari-Plattform
  • TPlatformChrome (11): Chrome-Plattform
  • TPlatformFirefox (12): Firefox-Plattform

Tag-Operationstypen:

  • TTagOperationSet (0): Tag-Wert setzen (bestehenden Wert ersetzen)
  • TTagOperationAppend (1): An Tag-Wert anhängen (zur Liste hinzufügen)
  • TTagOperationRemove (2): Tag-Wert entfernen (aus der Liste entfernen)
  • TTagOperationIncrement (3): Tag-Wert inkrementieren (numerische Erhöhung)

Vorteile:

  • Einzelner API-Aufruf: Registrieren Sie mehrere Geräte und Kanäle auf einmal
  • Atomare Operation: Alle Registrierungen gelingen oder scheitern gemeinsam
  • Benutzerzentriert: Ordnet alle Geräte einem einzigen Benutzerprofil zu
  • Erweitertes Tagging: Unterstützt komplexe Tag-Operationen
  • Plattformübergreifend: Behandeln Sie mehrere Plattformen gleichzeitig

Beispiel für das Senden von Tags an Pushwoosh:

Pushwoosh.push((api) => {
  var myCustomTags = {
    'Tag 1': 123,
    'Tag 2': 'some string'
  };
  api.setTags(myCustomTags)
    .then((res) => {
      var skipped = res && res.skipped || [];
      if (!skipped.length) {
        console.log('success');
      }
      else {
        console.warn('skipped tags:', skipped);
      }
    })
    .catch((err) => {
      console.error('setTags error:', err);
    });
});

Tag-Wert inkrementieren

Anchor link to

Um einen Wert eines Zahlen-Tags zu inkrementieren, verwenden Sie den operation-Parameter mit dem Wert ‘increment’ wie folgt:

Pushwoosh.push((api) => {
  api.setTags({
    'Tag 1': {
      operation: 'increment',
      value: 1
    }
  })
});

Tag-Werte anhängen

Anchor link to

Um neue Werte an das bestehende Listen-Tag anzuhängen, verwenden Sie den operation-Parameter mit dem Wert ‘append’ wie folgt:

Pushwoosh.push((api) => {
  api.setTags({
    'Tag 3': {
      operation: 'append',
      value: ['Value3']
    }
  })
});

Tag-Wert entfernen

Anchor link to

Um einen Wert aus einem Listen-Tag zu entfernen, verwenden Sie den operation-Parameter mit dem Wert ‘remove’ wie folgt:

Pushwoosh.push((api) =>{
  api.setTags({
    'Tag 3': {
      operation: 'remove',
      value: ['Value2']
    }
  })
});

Öffentliche Methoden

Anchor link to

Pushwoosh.subscribe()

Diese Methode wird verwendet, um die Erlaubnis eines Benutzers für Push-Benachrichtigungen anzufordern. Wenn ein Benutzer bereits angemeldet ist, wird die Ausführung der Methode beendet.

Wenn ein Benutzer noch nicht für Pushes angemeldet ist:

1. Die Erlaubnis für Push-Benachrichtigungen wird angefordert.

2. Wenn ein Benutzer Benachrichtigungen zulässt, wird das onSubscribe-Ereignis ausgelöst.

Pushwoosh.subscribe() wird automatisch ausgeführt, wenn autoSubscribe: true. während der SDK-Initialisierung gesetzt ist.

Rufen Sie diese Methode auf, wenn Sie sich entschieden haben, einen Benutzer manuell zur Anmeldung für Pushes aufzufordern, indem Sie den Parameter autoSubscribe: false während der Initialisierung verwenden:

<button onclick="Pushwoosh.subscribe()">Subscribe</button>
<script>
  Pushwoosh.push(['onSubscribe', (api) => {
    console.log('User successfully subscribed');
  }]);
</script>

Pushwoosh.unsubscribe()

  1. Die /unregisterDevice-Methode wird ausgeführt.
  2. Das onUnsubscribe-Ereignis wird ausgelöst.
<button onclick="Pushwoosh.unsubscribe()">Unsubscribe</button>
<script type="text/javascript">
  Pushwoosh.push(['onUnsubscribe', (api) => {
    console.log('User successfully unsubscribed');
  }]);
</script>

Pushwoosh.isSubscribed()

Prüft, ob ein Benutzer angemeldet ist und gibt ein true/false-Flag zurück.

Pushwoosh.isSubscribed().then((isSubscribed) => {
  console.log('isSubscribed', isSubscribed);
});

Pushwoosh.getHWID()

Gibt die Pushwoosh HWID zurück.

Pushwoosh.getHWID().then((hwid) => {
  console.log('hwid:', hwid);
});

Pushwoosh.getPushToken()

Gibt den Push-Token zurück, falls verfügbar.

Pushwoosh.getPushToken().then((pushToken) => {
  console.log('pushToken:', pushToken);
});

Pushwoosh.getUserId()

Gibt die User ID zurück, falls verfügbar.

Pushwoosh.getUserId().then((userId) => {
  console.log('userId:', userId);
});

Pushwoosh.getParams()

Gibt eine Liste der folgenden Parameter zurück:

Pushwoosh.getParams().then((params) => {
  params = params || {};
  var hwid = params.hwid;
  var pushToken = params.pushToken;
  var userId = params.userId;
});

Pushwoosh.isAvailableNotifications()

Prüft, ob ein Browser das Pushwoosh WebSDK 3.0 unterstützt, gibt ‘true’ oder ‘false’ zurück.

Pushwoosh.isAvailableNotifications() // true/false

InboxMessages-Methoden

Anchor link to

messagesWithNoActionPerformedCount(): Promise<number>

Gibt die Anzahl der geöffneten Nachrichten zurück.

Pushwoosh.pwinbox.messagesWithNoActionPerformedCount()
  .then((count) => {
    console.log(`${count} messages opened`);
  });

unreadMessagesCount()

Gibt die Anzahl der ungelesenen Nachrichten zurück.

Pushwoosh.pwinbox.unreadMessagesCount()
  .then((count) => {
    console.log(`${count} messages unread`);
  });

messagesCount(): Promise<number>

Gibt die Gesamtzahl der Nachrichten zurück.

Pushwoosh.pwinbox.messagesCount()
  .then((count) => {
    console.log(`${count} messages`);
  });

loadMessages(): Promise<Array>

Lädt die Liste der nicht gelöschten Nachrichten.

Pushwoosh.pwinbox.loadMessages()
  .then(() => {
    console.log('Messages have been loaded');
  });

readMessagesWithCodes(codes: Array<string>): Promise<void>

Markiert Nachrichten anhand von Inbox_Ids als gelesen.

Pushwoosh.pwinbox.readMessagesWithCodes(codes)
  .then(() => {
    console.log('Messages have been read');
  });

performActionForMessageWithCode(code: string): Promise<void>

Führt die einer Nachricht zugewiesene Aktion aus und markiert die Nachricht als gelesen.

Pushwoosh.pwinbox.performActionForMessageWithCode(code)
  .then(() => {
    console.log('Action has been performed');
  });

deleteMessagesWithCodes(codes: Array<string>): Promise<void>

Markiert Nachrichten als gelöscht.

Pushwoosh.pwinbox.deleteMessagesWithCodes([code])
  .then(() => {
    console.log('Messages have been deleted');
  });

syncMessages(): Promise<void>

Synchronisiert Nachrichten mit dem Server.

Pushwoosh.pwinbox.syncMessages()
  .then(() => {
    console.log('Messages have been synchronized');
  });

Unterstützung für Progressive Web Apps

Anchor link to

Um Pushwoosh in Ihre Progressive Web Application (PWA) zu integrieren, befolgen Sie die unten beschriebenen Schritte.

1. Kopieren Sie den Pfad zu Ihrer Service-Worker-Datei:

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/service-worker.js') // <- your service worker url
  });
}

Verwenden Sie dann den Parameter serviceWorkerUrl bei der Initialisierung des WebSDK wie folgt:

var Pushwoosh = Pushwoosh || [];
Pushwoosh.push(['init', {
  logLevel: 'error',
  applicationCode: 'XXXXX-XXXXX',
  safariWebsitePushID: 'web.com.example.domain',
  defaultNotificationTitle: 'Pushwoosh',
  defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',
  serviceWorkerUrl: '/service-worker.js', // <- your service worker url
}]);

Das WebSDK registriert den neuen Service Worker nicht sofort; ein Service Worker wird registriert, wenn er benötigt wird:

  • wenn ein Gerät einen Push-Token erhält (bei der Geräteregistrierung oder erneuten Anmeldung),
  • wenn ein Push-Token gelöscht wird (beim Entfernen eines Geräts aus der Benutzerbasis).

Es beschleunigt das Laden Ihrer Seiten, indem die Anzahl der Serveranfragen verkürzt wird.

Browser erlauben nicht, dass zwei verschiedene Service Worker gleichzeitig registriert werden (lesen Sie mehr: https://github.com/w3c/ServiceWorker/issues/921), daher sollte für Ihre Codebasis und die Pushwoosh-Codebasis ein gemeinsamer Service Worker registriert werden, damit Ihre PWA korrekt funktioniert.

2. Fügen Sie die folgende Zeichenfolge zu Ihrem Service Worker hinzu (am Anfang oder am Ende, es spielt keine Rolle):

importScripts('https://cdn.pushwoosh.com/webpush/v3/pushwoosh-service-worker.js' + self.location.search);

So ermöglichen Sie Ihrem Service Worker den Empfang und die Verarbeitung von Push-Benachrichtigungen, die über Pushwoosh-Dienste gesendet werden.

Installation über den Google Tag Manager

Anchor link to

Verwenden Sie den folgenden Code in Ihrem Google Tag Manager, um das Pushwoosh SDK zu initialisieren. Erstellen Sie ein benutzerdefiniertes HTML-Tag und fügen Sie den folgenden Code ein. Stellen Sie sicher, dass Sie Ihren Pushwoosh Application Code, Ihre Safari Website ID und die URL des Standard-Benachrichtigungsbildes ändern.
Setzen Sie außerdem eine hohe Tag Firing-Priorität (z. B. 100) und lösen Sie es auf Allen Seiten aus. Siehe unten für einen Screenshot.Kopieren

<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>
<script type="text/javascript">
  var Pushwoosh = Pushwoosh || [];
  Pushwoosh.push(['init', {
    logLevel: 'error',
    applicationCode: 'XXXXX-XXXXX',
    safariWebsitePushID: 'web.com.example.domain',
    defaultNotificationTitle: 'Pushwoosh',
    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',
    autoSubscribe: true,
    subscribeWidget: {
      enable: false
    },
    userId: 'user_id'
  }]);
</script>