Widget d'abonnement

Le widget d’abonnement est une invite et une cloche de lancement qui incitent les visiteurs du site à s’abonner aux notifications push, configurées ensemble via subscriptionWidget mais activées indépendamment : l’invite seule, la cloche seule, ou les deux à la fois. Activer l’une ou l’autre remplace le bouton d’abonnement aux notifications push, le Popup d’abonnement personnalisé et l’invite d’abonnement — tant qu’au moins une des deux parties est activée, aucun de ces trois anciens widgets ne se charge sur la page.

Un visiteur qui n’a pas encore décidé voit la demande de l’invite. Un visiteur qui a déjà bloqué les notifications voit à la place une explication sur la façon de les débloquer.

Prérequis

Assurez-vous d’avoir implémenté Pushwoosh Web SDK 3.0 sur votre site. Pour cela, suivez notre guide d’intégration.

1. Activer l’invite et la cloche

Ajoutez le paramètre subscriptionWidget à l’initialisation du WebSDK et définissez prompt.enabled et/ou launcher.enabled sur true :

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: { enabled: true },
    launcher: { enabled: true },
  }
}]);

Pas d'interrupteur unique de niveau supérieur

subscriptionWidget.enable au niveau supérieur n’est pas lu. Définir uniquement ce champ n’active rien. Voir Migration depuis les anciens widgets ci-dessous.

Chaque champ ci-dessous est facultatif. Un champ omis revient à sa valeur par défaut. Dans l’extrait d’initialisation, un nombre hors de sa plage est silencieusement ramené à la borne la plus proche, et une valeur d’énumération invalide revient silencieusement à sa valeur par défaut, sans avertissement dans la console. Les formulaires du Panneau de configuration décrits plus loin valident chaque champ et refusent d’enregistrer une valeur invalide.

2. Configurer l’invite et la cloche

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: {
      enabled: true,
      layout: 'card',       // 'card' | 'bar' | 'modal'
      position: 'bottom-right',
      iconUrl: 'https://url-image.png',
      borderRadius: 12,     // 0–32
      overlay: false,
    },
    launcher: {
      enabled: true,
      position: 'bottom-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
      offset: 20,           // 0–100
      width: 48,             // 16–200
      height: 48,            // 16–200
      imageUrl: 'https://url-image.png',
      background: '#4285f4',
      iconColor: '#ffffff',
    },
    display: {
      trigger: 'auto',      // 'auto' | 'launcher' | 'manual'
      delay: 5,             // seconds, 0–3600
      cappingCount: 3,      // auto-shows per visitor, 0–100, 0 = unlimited
      cappingInterval: 24,  // hours between auto-shows, 0–8760
    },
    texts: {
      title: 'Stay in the loop',
      message: 'Get notified about news and updates.',
      acceptText: 'Allow',
      declineText: 'Not now',
      closeText: 'Close',
      blockedTitle: 'Notifications are blocked',
      blockedMessage: 'Enable notifications in your browser settings to stay updated.',
      launcherLabel: 'Subscribe to notifications',
      launcherBlockedLabel: 'Notifications are blocked',
    },
    colors: {
      background: '#ffffff',
      accent: '#4285f4',
      text: '#000000',
      textSecondary: '#666666',
    },
  }
}]);

Mise en page et position

prompt.layout définit la forme de l’invite :

• card — une carte compacte ancrée à un bord ou un coin. prompt.position accepte top, bottom, top-left, top-right, bottom-left ou bottom-right.
• bar — une barre occupant toute la largeur de la page. prompt.position n’accepte que top ou bottom.
• modal — une fenêtre centrée sur la page. prompt.position est toujours center.

Consultez la liste ci-dessus pour connaître la mise en page définie avant de choisir une position. Dans l’extrait d’initialisation, une position non prise en charge par la mise en page actuelle est silencieusement remplacée par la valeur par défaut de cette mise en page. Le formulaire du Panneau de configuration rejette cette combinaison à la place.

Quand afficher l’invite

display.trigger contrôle ce qui ouvre l’invite :

• auto — s’ouvre automatiquement display.delay secondes après le chargement de la page, puis à nouveau toutes les display.cappingInterval heures si le visiteur n’a pas décidé, jusqu’à display.cappingCount fois au total (0 signifie sans limite).
• launcher — ne s’ouvre jamais sur un minuteur. Définissez-le avec launcher.enabled: true pour qu’un clic sur la cloche puisse l’ouvrir. L’API manuelle l’ouvre quand même, quel que soit ce réglage ou l’état de la cloche.
• manual — s’ouvre uniquement via Pushwoosh.moduleRegistry.subscriptionWidget, décrit plus loin.

display.delay, display.cappingCount et display.cappingInterval ne s’appliquent qu’au déclencheur auto.

La cloche de lancement

launcher.enabled affiche une cloche flottante à un visiteur qui peut encore agir sur la demande (pas encore abonné, ou bloqué), indépendamment de l’invite et de display.trigger. La cloche reste à l’écran tant que l’invite est ouverte. launcher.position la place dans l’un des quatre coins. launcher.offset définit sa distance par rapport aux bords, en pixels.

L’effet d’un clic sur la cloche dépend de l’invite. Si prompt.enabled vaut true, le clic la bascule : il l’ouvre, ou la ferme si elle est déjà ouverte. Si l’invite est désactivée, le clic demande directement l’autorisation au navigateur, comme Pushwoosh.subscribe() — sauf si le visiteur a déjà bloqué les notifications, auquel cas le clic ne fait rien.

launcher.width et launcher.height définissent la taille de la cloche en pixels (16–200, 48 par défaut pour chacun). launcher.imageUrl affiche une image à la place du bouton rond en forme de cloche. launcher.background et launcher.iconColor définissent la couleur de fond et celle du pictogramme du bouton rond. Sans valeur, launcher.background prend par défaut la couleur d’accentuation de la palette, et launcher.iconColor une couleur de pictogramme calculée pour contraster avec elle.

Textes et couleurs

texts.blockedTitle, texts.blockedMessage et texts.closeText s’affichent à la place de la demande une fois que le navigateur signale que le visiteur a bloqué les notifications — texts.acceptText et texts.declineText n’apparaissent jamais dans cet état. texts.launcherLabel et texts.launcherBlockedLabel sont l’infobulle de la cloche dans chaque état. Chaque champ de texte accepte jusqu’à 300 caractères.

colors.accent, colors.background, colors.text et colors.textSecondary acceptent une valeur hexadécimale ou un nom de couleur CSS. Les formulaires du Panneau de configuration valident chacun de ces champs, ainsi que launcher.background/launcher.iconColor, de cette manière, jusqu’à 64 caractères. L’extrait d’initialisation accepte n’importe quelle chaîne non vide pour colors.* sans vérifier son format ni sa longueur. Pour launcher.background/launcher.iconColor, il ne vérifie pas non plus le format, mais tronque silencieusement la valeur à 64 caractères.

Note

Une palette en mode sombre, launcher.zIndex et une fontFamily personnalisée sont disponibles comme champs supplémentaires réservés à l’initialisation. Ils ne sont pas exposés dans les formulaires du Panneau de configuration décrits ci-dessous.

Le gérer dans le Panneau de configuration

Applications gérées depuis le panneau uniquement

Les cartes du Panneau de configuration ne sont disponibles que pour les applications dont la plateforme Web est en mode géré depuis le panneau (voir Web Push SDK 3.0). Pour une application configurée par extrait de code, définissez subscriptionWidget dans l’extrait d’initialisation comme indiqué ci-dessus.

Sur une application gérée depuis le panneau, allez dans Settings → Configure platforms → Web. L’invite et la cloche y sont deux cartes distinctes, chacune avec son propre badge On/Off et son bouton Configure :

• Subscription invitation modifie l’invite : Invitation (mise en page, position, icône), When to show (déclencheur, délai, plafonnement), Texts et Colors.
• Subscription bell modifie le lanceur : position, URL de l’image, largeur/hauteur, couleur de fond et du pictogramme, et ses propres textes d’infobulle.

Le bouton Configure de chaque carte ouvre un aperçu en direct à côté du formulaire. L’aperçu n’affiche rien tant que l’interrupteur de cette carte est désactivé. Une fois activé, une liste déroulante au-dessus de l’aperçu permet de basculer entre la demande destinée au visiteur indécis et l’explication destinée au visiteur bloqué. L’enregistrement d’une carte ne remplace que sa moitié de la copie de la configuration du widget dans le panneau — les réglages de l’autre carte et l’extrait d’initialisation WebSDK sur votre site ne sont pas touchés.

Tant qu’une application est gérée depuis le panneau, les valeurs enregistrées dans l’une ou l’autre carte remplacent les mêmes clés dans l’extrait d’initialisation du site.

3. Contrôler l’invite depuis votre code

Une fois le paquet du widget chargé, il publie une API à l’adresse Pushwoosh.moduleRegistry.subscriptionWidget :

Pushwoosh.moduleRegistry.subscriptionWidget.show();          // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.hide();          // Closes the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.toggle();        // Toggles the current state
Pushwoosh.moduleRegistry.subscriptionWidget.toggle(true);    // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.isVisible();     // Returns whether the prompt is open

show() et toggle() n’ont aucun effet tant que prompt.enabled vaut false, ni pour un visiteur déjà abonné. Ouvrir l’invite déclenche un événement show-subscription-widget. La fermer déclenche hide-subscription-widget :

Pushwoosh.addEventHandler('show-subscription-widget', function() {
  console.log('Triggered event: show-subscription-widget');
});

Pushwoosh.addEventHandler('hide-subscription-widget', function() {
  console.log('Triggered event: hide-subscription-widget');
});

Migration depuis les anciens widgets

Le bouton d’abonnement aux notifications push, le Popup d’abonnement personnalisé et l’invite d’abonnement continuent de fonctionner tel que documenté sur leurs propres pages tant que subscriptionWidget.prompt.enabled et subscriptionWidget.launcher.enabled du site restent tous deux non définis ou false. En activer un seul arrête le chargement des trois, aussi bien sur une application configurée par extrait de code que sur une application gérée depuis le panneau.

Attention

Une version antérieure du widget utilisait un unique interrupteur subscriptionWidget.enable de niveau supérieur à la place de prompt.enabled/launcher.enabled. Cette forme n’est plus lue. Un extrait qui ne définit encore que enable: true désactive désormais entièrement le widget : ni l’invite ni la cloche n’affichent rien, le WebSDK écrit dans la console une indication nommant les deux champs à définir à la place, et les trois anciens widgets se chargent comme si subscriptionWidget n’avait jamais été défini. Faire passer une application gérée depuis le panneau au nouveau widget ne reprend pas non plus les réglages de l’ancien widget qu’il remplace — chaque carte démarre avec ses propres valeurs par défaut.