Communication avec les cadres intégrés
Cet article explique comment la communication diffère entre un document intégrateur et le contenu intégré dans différents types de cadres (c'est-à-dire un élément HTML <iframe> et un élément HTML <fencedframe>), ainsi que la façon dont les données transmises peuvent être stockées.
Comment communiquer entre l'intégrateur et un <iframe>
Lorsque du code tiers est intégré dans un <iframe>, l'<iframe> et l'intégrateur peuvent s'envoyer librement des messages pour demander l'écriture de données dans leur stockage partagé côté client. L'intégrateur peut envoyer une requête à cet <iframe> pour écrire des données dans son propre stockage tiers via un canal de communication inter-document utilisant Window.postMessage(). Le tiers peut aussi envoyer des requêtes postMessage() à l'intégrateur.
Depuis l'<iframe>, vous pouvez écouter un événement message provenant de l'intégrateur. Lorsque l'intégrateur envoie un message à l'<iframe> via postMessage(), l'<iframe> peut récupérer ces données et les stocker dans son propre stockage partagé côté client. Inversement, l'<iframe> peut envoyer un message que l'intégrateur peut écouter, et répondre en écrivant des données dans son stockage partagé.
Comment communiquer entre l'intégrateur et un <fencedframe>
Les fenced frames sont conçus pour des cas comme l'affichage de publicités ciblées sélectionnées via l'API Protected Audience et WindowSharedStorage.selectURL(). La communication entre les <fencedframe> et d'autres pages en dehors du <fencedframe> sur la page est volontairement limitée, mais il existe une méthode de communication entre l'intégrateur et les worklets de stockage partagé : FencedFrameConfig.setSharedStorageContext().
Note :
Au sein d'un même arbre de <fencedframe>, la communication entre cadres est autorisée. Par exemple, un <fencedframe> racine peut envoyer un message à un <iframe> enfant dans son propre arbre, et un <iframe> enfant peut envoyer un message au <fencedframe> parent.
Voyons un exemple plus complexe qui utilise une opération de sortie Select URL pour afficher une publicité dans un <fencedframe>.
Dans cet exemple, un éditeur demande à un fournisseur de contenu tiers d'afficher du contenu sur la page. Le contenu choisi avec WindowSharedStorage.selectURL() est affiché dans un <fencedframe>, et ce contenu contient un <iframe> provenant d'un fournisseur de mesure. Notez qu'un éditeur peut représenter toute entité qui intègre un <fencedframe> tiers. Un fournisseur de mesure représente tout code tiers imbriqué s'exécutant dans un <fencedframe> d'un autre tiers.
Pour transmettre des données à un <fencedframe> à utiliser dans un worklet de stockage partagé, l'intégrateur peut définir les données dans un FencedFrameConfig. Cette valeur sera disponible sous WorkletSharedStorage.context à l'intérieur du worklet de stockage partagé. Ces données ne sont pas accessibles en dehors d'un worklet, et ne peuvent être consultées que dans l'environnement sécurisé et privé qu'offre un worklet de stockage partagé.
Quand un appel à selectURL() retourne un FencedFrameConfig, l'intégrateur du cadre peut transmettre des données en appelant setSharedStorageContext(data) :
const fencedFrameConfig = await window.sharedStorage.selectURL(
"creative-rotation",
urls,
{
// …
resolveToConfig: true,
},
);
fencedFrameConfig.setSharedStorageContext("des-donnees");
// Naviguer le fenced frame vers la config.
document.getElementById("my-fenced-frame").config = fencedFrameConfig;
setSharedStorageContext(data) doit être appelé sur le fencedFrameConfig avant que l'élément <fencedframe> destinataire ait son attribut config défini sur fencedFrameConfig, car cela déclenche la navigation du cadre.
À l'intérieur d'un worklet de stockage partagé, on peut alors accéder à WorkletSharedStorage.context pour récupérer les données :
class ReportingOperation {
async run() {
sharedStorage.set("des-donnees-de-l-integrateur", sharedStorage.context);
}
}
register("send-report", ReportingOperation);