Guida all'integrazione diretta

Questa pagina descrive i passaggi necessari per integrare le notifiche web push utilizzando il metodo preferito, ovvero l'utilizzo di un service worker direttamente sul tuo sito web. Utilizzando questo metodo:

• Dovrai creare o aggiornare un service worker alla radice del tuo sito web.
• Le notifiche inviate agli utenti appariranno come provenienti direttamente dal tuo nome di dominio.

Requisiti

• Devi essere in grado di configurare il service worker allo scope radice del tuo sito web.
• Il service worker deve essere caricato dallo stesso dominio del tuo sito web — cioè, non può essere caricato da una CDN o da un'altra posizione di terze parti.
• Devi essere in grado di includere lo script di notifica web push di Fanplayr all'interno del service worker.

Se non sei in grado di soddisfare i requisiti di questo metodo, consulta Integrazione tramite Popup per un metodo alternativo.

Limitazioni

Supporto browser

Supportato dai browser web e sistemi operativi moderni che implementano la Push API.

Dispositivo	Browser	Supporto
Desktop	Chrome	v42+
Desktop	Edge	v17+ Nota: Edge spesso nasconde le richieste di notifica dietro una piccola icona a "campana" (🕭) nella barra degli URL, rendendo più difficile per gli utenti notare la richiesta.
Desktop	Firefox	v44+
Desktop	Opera	v29+
Desktop	Safari	v16+ su macOS Ventura
Mobile	Chrome Android	v42+
Mobile	Firefox for Android	v48+
Mobile	Opera for Android	v29+
Mobile	Safari on iOS	Non supportato

INFO

Quando si utilizza un widget Fanplayr per chiedere agli utenti di iscriversi, è opportuno utilizzare il filtro di segmentazione "Può iscriversi alle Notifiche Web Push" per assicurarsi che solo gli utenti che attualmente non hanno un abbonamento e che hanno un browser web supportato siano targettizzati con il widget.

Esperienza Utente

1. Richiedere il permesso di inviare notifiche: Agli utenti che non si sono ancora iscritti alle notifiche viene mostrato un widget con un messaggio che li invita a iscriversi (ad esempio "Resta aggiornato con le nostre ultime notizie e offerte"). Quando l'utente clicca sulla call to action principale, il browser gli chiede il permesso di inviare notifiche push.
2. L'utente concede il permesso: Se l'utente accetta di ricevere notifiche push, può cliccare su "Consenti" o "Sì" sulla richiesta del browser. A questo punto viene creata una sottoscrizione e memorizzata nel database di Fanplayr, che viene poi utilizzata per inviare notifiche.
3. Fanplayr invia notifiche push: La tua attività invia notifiche agli utenti iscritti tramite il servizio di messaggistica di Fanplayr. Gli utenti potranno vedere queste notifiche sul loro dispositivo ogni volta che il loro browser è aperto, anche se non stanno visitando direttamente il tuo sito web.

Best Practices

È altamente raccomandato utilizzare le funzionalità di Targeting di Fanplayr per visualizzare un widget intermedio che chieda agli utenti se sono interessati a iscriversi alle notifiche prima di richiedere effettivamente il permesso al browser. Questo è importante per una serie di motivi:

• Se un utente blocca la richiesta di permesso del browser per abilitare le notifiche, non potrai richiedere nuovamente il permesso a meno che l'utente non reimposti esplicitamente il permesso nelle impostazioni del browser.
• Molti browser web stanno diventando sempre più restrittivi e possono impedire la visualizzazione delle richieste di permesso quando vengono generate programmaticamente senza alcuna interazione dell'utente — cioè, evita di mostrare la richiesta di permesso del browser immediatamente quando un utente arriva sulla pagina, mostra invece una call to action che, una volta cliccata, attiva la richiesta.

Guida all'Integrazione

Devi essere in grado di configurare il service worker allo scope radice del tuo sito web. Questo può essere ottenuto in uno dei due modi:

• Ospitando il file JavaScript del service worker alla radice del tuo sito web — ad esempio, se il tuo dominio è mybrand.com e il tuo file service worker si trova all'indirizzo https://mybrand.com/service-worker.js, il service worker sarà attivo alla radice per impostazione predefinita.
• In alternativa, ospitando il file JavaScript del service worker in una sottodirectory e assicurandoti che la risposta per il file dal server contenga un'intestazione speciale Service-Worker-Allowed: /, consentendo al browser di renderlo attivo alla radice del sito web.

Segui una delle guide di istruzioni qui sotto che meglio si adatta al tuo scenario:

Se il tuo sito web ha GIÀ un service worker

Segui questa sezione se il tuo sito web ha già un service worker. Ti guiderà su come includere lo script di notifica web push di Fanplayr nel tuo codice service worker esistente.

Si presume che il tuo service worker esistente soddisfi i requisiti delineati all'inizio di questo documento, ovvero che sia configurato per essere eseguito allo scope radice del tuo sito web.

1. Includi il nostro script nel tuo service worker esistente

Aggiungi il seguente contenuto al tuo file JavaScript del service worker per importare lo script di Fanplayr per la gestione delle notifiche web push:

var fanplayrOptions = {
  version: 1,
  // Quando `true`, Fanplayr aggiungerà handler per gli eventi "install" e "activate"
  // al Service Worker, il che lo farà installare e attivare
  // immediatamente senza attendere il caricamento delle cache.
  // Imposta su `false` se il tuo Service Worker implementa uno di questi eventi.
  immediate: true
};
importScripts(
  'https://static.fanplayr.com/client/sw.js?v=' + fanplayrOptions.version
);

Nota: Valuta attentamente se l'opzione immediate debba essere abilitata in base alle esigenze del tuo sito web e alla logica esistente nel tuo service worker.

2. Includi lo snippet HTML

Includi il seguente HTML in tutte le pagine del tuo sito web. Questo istruisce la libreria JavaScript di Fanplayr che il tuo service worker è configurato per utilizzare questa funzionalità.

<script>
  window.fanplayrServiceWorker = true;
</script>

Se il tuo sito web NON ha un service worker

Segui questa sezione se il tuo sito web non utilizza ancora un service worker. Ti guiderà su come crearne uno.

1. Crea e carica il file del service worker

Crea un nuovo file JavaScript alla radice del tuo server web chiamato service-worker.js, con il contenuto mostrato sotto:

importScripts('https://static.fanplayr.com/client/sw.js');

Assicurati che questo file sia servito con il tipo di contenuto corretto Content-Type: text/javascript dal tuo server web.

Esempio 1

Il tuo nome di dominio è mybrand.com e puoi caricare il file del service worker alla radice del tuo sito web in modo che sia accessibile a https://mybrand.com/service-worker.js.

Esempio 2

Il tuo nome di dominio è mybrand.com, ma non puoi caricare il file del service worker alla radice del tuo sito web (forse perché stai utilizzando un sito web di e-commerce ospitato che non consente il caricamento di file alla radice).

Invece, carichi il file in una sottodirectory "assets" per renderlo accessibile a https://mybrand.com/assets/service-worker.js. Inoltre, configuri il tuo server web per includere l'intestazione Service-Worker-Allowed: / nella risposta del file in modo che i browser possano usarlo come service worker alla radice del tuo sito web.

2. Includi uno snippet HTML

Non eseguire questo passaggio a meno che non sia esplicitamente richiesto.

Includi il seguente snippet HTML su tutte le pagine del tuo sito web. Questo script istruisce i browser a utilizzare il file JavaScript che hai creato nel passaggio precedente come service worker per il tuo sito web.

<script
  src="https://static.fanplayr.com/client/sw-load.js"
  data-path="/service-worker.js"
></script>

Nota: Se hai utilizzato un nome file alternativo per il service worker, assicurati di aggiornare l'attributo data-path nello script per farlo corrispondere.

If your website DOES NOT have a service worker AND you are using Fanplayr's Salesforce Commerce Cloud plugin

Segui questa sezione se stai utilizzando il plugin SFCC di Fanplayr e non hai già un service worker sul tuo sito web. Se hai già un service worker, segui le istruzioni in Se il tuo sito web ha GIÀ un service worker.

1. Abilita il service worker

Naviga alla pagina di configurazione del plugin Fanplayr e abilita il service worker come mostrato nello screenshot qui sotto:

2. Rendi il service worker accessibile dalla radice

1. All'interno di SFCC, naviga a Business Manager / Merchant Tools / SEO / Aliases.
2. Modifica la configurazione dell'alias per aggiungere la seguente rotta, regolando se necessario per corrispondere al tuo hostname.

{
  "my-store.demandware.net" : [
    {
      "if-site-path": "/serviceWorker.js",
      "pipeline": "Fanplayr-ServiceWorker"
    }
  ]
}

Migrazione degli Abbonati Esistenti

Se in precedenza hai utilizzato un altro servizio per le notifiche web push sul tuo sito web, potrebbe essere possibile migrare alcune delle iscrizioni recenti create per i tuoi utenti a condizione che:

1. Tu possa fornire a Fanplayr un'esportazione dei dettagli degli abbonamenti utente attivi dall'altro servizio. Al minimo, deve includere i seguenti dettagli per ogni abbonamento utente:
   • Endpoint di sottoscrizione (esempio sotto)
   • Chiave p256dh di sottoscrizione (esempio sotto)
   • Chiave auth di sottoscrizione (esempio sotto)
2. Tu possa fornire a Fanplayr la coppia di chiavi pubbliche e private VAPID web push che sono state utilizzate per generare gli abbonamenti (esempio sotto)

# Esempio di chiave VAPID pubblica:
BCK1IQyb-o7-uqWBMgGM0UMZ_kRhvgr2evq3c0Yz2ZQsjH0mz1rxbq3j5i7mOlT7bljgq5lHBmPuvFmZ1jtNQV4

# Esempio di chiave VAPID privata:
XG5k9uNkfqbc9rW0_fsJmbSZfVYUKsEdtc7PeB2vU6s

# Esempio di endpoint di sottoscrizione (uno per utente):
https://fcm.googleapis.com/fcm/send/e9urHUUzfsc:APA91bEqiCiCLbxYiyoP0iuqxUwzzVOkMLic6CHgb7A0J4u75ME6EOFng_ts1b1-wJoIwaeSecH5ucvaxZ-9o08VaI4DwXpNPfmcvOPoXMZVLYJ9VXFCffakDDgVKU3xDAEO-wDq-Vrt

# Esempio di chiave p256dh di sottoscrizione (una per utente):
BJWvtiOEpgYCMFYHM8_hHo8bxm294DyFzOgpOubsRc21MVfl4z6BklEGzYVvYu3JVO7AjrghxCAcA5BPDlacT9s

# Esempio di chiave auth di sottoscrizione (una per utente):
OEBqFrdGvONmWXP-BDN4Qg

Limitazioni della Migrazione

1. È importante capire che Fanplayr potrebbe essere in grado di migrare solo una parte delle sottoscrizioni da un servizio precedentemente utilizzato, a causa di alcune sottoscrizioni che sono diventate naturalmente inattive o sono scadute nel frattempo.
2. È anche importante capire che le opzioni per l'invio di notifiche alle sottoscrizioni migrate potrebbero essere limitate fino a quando l'utente non torna al sito web dopo che il Targeting di Fanplayr è stato integrato sul tuo sito.
   • Questo perché Fanplayr non avrà alcuna conoscenza dell'utente dalla sola sottoscrizione migrata e richiederebbe che l'utente torni al sito web con la sua sottoscrizione per associare internamente la conoscenza di Fanplayr dell'utente con la sottoscrizione.
   • Nel frattempo, dovrebbe essere comunque possibile inviare notifiche push indirizzate a tutti gli abbonati senza filtri.

Risoluzione dei problemi

Il service worker non viene rilevato

Se stai usando lo script sw-load.js di Fanplayr, devi assicurarti che sia incluso nella tua pagina web prima del codice di tracciamento di Fanplayr.

Impossibile caricare il file JavaScript del service worker alla radice

Se non riesci a caricare il file JavaScript del service worker alla radice del tuo server, potresti comunque riuscire a procedere se puoi caricarlo altrove con intestazioni specifiche.

1. Assicurati che il tuo server stia consegnando il file del service worker con le seguenti intestazioni:
   1. Content-Type: text/javascript
   2. Service-Worker-Allowed: /
2. Se stai registrando manualmente il service worker (non utilizzando il nostro script sw-load.js), dovrai aggiornare il tuo codice per forzare il caricamento del worker allo scope radice. Ad esempio:

<script>
  if ('serviceWorker' in navigator) {
    // Nota: Sostituisci PATH_TO_SERVICE_WORKER con il percorso corretto sul tuo server.
    navigator.serviceWorker
      .register('/PATH_TO_SERVICE_WORKER/serviceWorker.js', {
        // Forza il caricamento del service worker nello scope radice.
        scope: '/'
      })
      .then(function () {
        window.fanplayrServiceWorker = true;
      });
  }
</script>