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', // mögliche Werte: error, info, debug
    applicationCode: 'XXXXX-XXXXX', // Ihr Application Code aus dem Pushwoosh Control Panel
    apiToken: 'XXXXXXX', //  Device API Token
    safariWebsitePushID: 'web.com.example.domain', // eindeutiger Reverse-Domain-String, den Sie in Ihrem Apple Developer Portal erhalten. Nur erforderlich, wenn Sie Push-Benachrichtigungen an den Safari-Browser senden
    defaultNotificationTitle: 'Pushwoosh', // legt einen Standardtitel für Push-Benachrichtigungen fest
    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // URL zu einem benutzerdefinierten Benachrichtigungsbild
    autoSubscribe: false, // oder true. Wenn true, wird ein Benutzer bei der SDK-Initialisierung aufgefordert, Pushes zu abonnieren
    subscribeWidget: {
      enable: true
    },
    userId: 'user_id', // optional, benutzerdefinierte User ID festlegen
    tags: {
        'Name': 'John Smith'     // optional, benutzerdefinierte Tags festlegen
    }
}]);
</script>

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 pushwoosh-service-worker.js-Datei 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 eines der SDK-Ereignisse zu abonnieren oder abzubestellen, verwenden Sie die Handler nach dem Laden des SDK:

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


  // Um ein Ereignis zu abonnieren:
  Pushwoosh.addEventHandler('event-name', onEventNameHandler)


  // Um ein Ereignis abzubestellen:
  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 Abonnement-Widgets

Anchor link to

Verfolgen Sie die Anzeige eines Abonnement-Aufforderungs-Widgets.

Pushwoosh.push(['onLoad', (api) => {
  // Wird bei der Anzeige des Abonnement-Aufforderungs-Widgets ausgeführt
  Pushwoosh.addEventHandler('show-subscription-widget', (payload) => {
    console.log('Triggered event: show-subscription-widget');
  });


  // Wird beim Ausblenden des Abonnement-Aufforderungs-Widgets ausgeführt
  Pushwoosh.addEventHandler('hide-subscription-widget', (payload) => {
    console.log('Triggered event: hide-subscription-widget');
  });
}]);

Ereignisse des Benachrichtigungsberechtigungsdialogs

Anchor link to

Verfolgen Sie die Anzeige des nativen Abonnementdialogs.

Pushwoosh.push(['onLoad', function (api) {
  // Wird bei der Anzeige des Berechtigungsdialogs ausgeführt
  Pushwoosh.addEventHandler('show-notification-permission-dialog', (payload) => {
    console.log('Triggered event: show-notification-permission-dialog');
  });


  // Wird beim Ausblenden des Berechtigungsdialogs mit einem von drei möglichen Status ausgeführt:
  // 1. default - der Dialog wird geschlossen
  // 2. granted - die Berechtigung wird erteilt
  // 3. denied - die Berechtigung wird verweigert
  Pushwoosh.addEventHandler('hide-notification-permission-dialog', (payload) => {
    console.log('Triggered event: hide-notification-permission-dialog', payload.permission);
  });
}]);

Berechtigungsereignisse

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) => {
  // Wird während der SDK-Initialisierung ausgeführt, wenn 'autoSubscribe: false' oder/und wenn ein Benutzer eine Push-Benachrichtigungsaufforderung ignoriert.
  Pushwoosh.addEventHandler('permission-default', (payload) => {
    console.log('Triggered event: permission-default');
  });


  // Wird während der SDK-Initialisierung ausgeführt, wenn Benachrichtigungen blockiert sind oder sobald ein Benutzer Push-Benachrichtigungen blockiert.
  Pushwoosh.addEventHandler('permission-denied', (payload) => {
    console.log('Triggered event: permission-denied');
  });


  // Wird während der SDK-Initialisierung ausgeführt, wenn Benachrichtigungen erlaubt sind oder sobald ein Benutzer Push-Benachrichtigungen erlaubt.
  Pushwoosh.addEventHandler('permission-granted', (payload) => {
    console.log('Triggered event: permission-granted');
  });
}]);

Receive-Push-Ereignis

Anchor link to

Verfolgen Sie die Zustellung von Push-Benachrichtigungen an ein Gerät.

Pushwoosh.push(['onLoad', (api) => {
  // Wird ausgeführt, wenn eine Push-Benachrichtigung angezeigt wird.
  Pushwoosh.addEventHandler('receive-push', (payload) => {
    console.log('Triggered event: receive-push', payload.notification);
  });
}]);

Benachrichtigungsereignisse

Anchor link to

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

Pushwoosh.push(['onLoad', (api) => {
  // Wird ausgeführt, wenn ein Benutzer auf eine Benachrichtigung klickt.
  Pushwoosh.addEventHandler('open-notification', (payload) => {
    console.log('Triggered event: open-notification', payload.notification);
  });


  // Wird ausgeführt, wenn ein Benutzer eine Push-Benachrichtigung schließt.
  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) => {
  // Wird vom ServiceWorker ausgeführt, nachdem die Inbox-Nachricht empfangen und in indexedDB gespeichert wurde.
  Pushwoosh.addEventHandler('receive-inbox-message', (payload) => {
    console.log('Triggered event: receive-inbox-message', payload.message);
  });


  // Wird ausgeführt, nachdem die Inbox während des Ladens der Seite automatisch aktualisiert wurde.
  Pushwoosh.addEventHandler('update-inbox-messages', (payload) => {
    console.log('Triggered event: receive-inbox-message', payload.messages);
  });
}]);

Ereignisse für benutzerdefinierte Abonnement-Popups

Anchor link to

Details zur Behandlung von Ereignissen für benutzerdefinierte Abonnement-Popups finden Sie im Leitfaden zu Ereignissen für benutzerdefinierte Abonnement-Popups.

API

Anchor link to

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

Pushwoosh.push((api) => {
  // Tags für einen Benutzer festlegen
  api.setTags({
    'Tag Name 1': 'value1',
    'Tag Name 2': 'value2'
  });


  // Tags für einen Benutzer vom Server abrufen
  api.getTags();


  // Benutzer-ID registrieren
  api.registerUser('user123');


    // Benutzer-E-Mail registrieren
  api.registerEmail('user@example.com');


  // SMS-Nummer registrieren
  api.registerSmsNumber('+15551234567');


  // WhatsApp-Nummer registrieren
  api.registerWhatsappNumber('+1234567890');


  // Ein Ereignis posten
  api.postEvent('myEventName', {attributeName: 'attributeValue'});


  //Von Benachrichtigungen abmelden
  api.unregisterDevice();


  // Alternativ Multi-Registrierung eines Benutzers mit Geräten und Kanälen
  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: Benutzerkennung
    email: 'user@example.com',       // Optional: E-Mail für E-Mail-Nachrichten
    sms_phone_number: '+1234567890', // Optional: SMS-Telefonnummer (E.164-Format)
    whatsapp_phone_number: '+1234567890', // Optional: WhatsApp-Nummer (E.164-Format)
    kakao_phone_number: '+1234567890',    // Optional: KakaoTalk-Nummer (E.164-Format)
    language: 'en',                  // Optional: Sprachcode (ISO 639-1)
    timezone: 'America/New_York',    // Optional: Zeitzonen-Kennung
    city: 'New York',               // Optional: Stadt für Targeting
    country: 'US',                  // Optional: Land für Targeting
    state: 'NY',                    // Optional: Bundesland für Targeting
    tags: {                         // Optional: Tag-Werte mit Operationen
      'UserType': {
        operation: TTagOperationSet,     // Tag-Wert setzen (0)
        value: 'Premium'
      },
      'Interests': {
        operation: TTagOperationAppend,  // An Tag-Wert anhängen (1)
        values: ['sports', 'technology']
      },
      'LoginCount': {
        operation: TTagOperationIncrement, // Tag-Wert inkrementieren (3)
        value: '1'
      }
    },
    push_devices: [                 // Optional: Array von Push-Geräten
      {
        hwid: 'web-device-456',
        platform: TPlatformChrome, // Chrome-Plattform (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:

  • Einziger API-Aufruf: Registrieren Sie mehrere Geräte und Kanäle auf einmal
  • Atomare Operation: Alle Registrierungen sind entweder erfolgreich oder schlagen gemeinsam fehl
  • 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 Number-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 List-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 List-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 abonniert ist, wird die Ausführung der Methode beendet.

Wenn ein Benutzer noch keine Pushes abonniert hat:

1. Die Berechtigung 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 zum Abonnieren von Pushes aufzufordern, indem Sie den Parameter autoSubscribe: false während der Initialisierung verwenden:

<button onclick="Pushwoosh.subscribe()">Abonnieren</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()">Abbestellen</button>
<script type="text/javascript">
  Pushwoosh.push(['onUnsubscribe', (api) => {
    console.log('User successfully unsubscribed');
  }]);
</script>

Pushwoosh.isSubscribed()

Prüft, ob ein Benutzer abonniert 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, folgen Sie den unten beschriebenen Schritten.

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).

Dies 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 ein gemeinsamer Service Worker für Ihre Codebasis und die Pushwoosh-Codebasis registriert werden, damit Ihre PWA korrekt funktioniert.

2. Fügen Sie die folgende Zeile 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 unten stehenden Code ein. Stellen Sie sicher, dass Sie Ihren Pushwoosh Application Code, die Safari Website ID und die URL des Standard-Benachrichtigungsbildes ändern.
Setzen Sie außerdem eine hohe Tag-Auslöseprioritä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>