Partage via

S’inscrire à l’API sélection d’annonces

  • Article

L’API de sélection d’annonces fournit des publicités pertinentes pour l’utilisateur sur votre site sans utiliser de cookies tiers. Consultez Vue d’ensemble de la sélection d’annonces dans le privacy-preserving-ads référentiel.

L’API de sélection d’annonces peut être utilisée par :

  • Vendeurs exécutant une plateforme côté offre (SSP), qui peuvent utiliser l’API pour fournir des publicités de meilleure qualité à leurs éditeurs.
  • Les acheteurs exécutant une plateforme côté demande (DSP), qui peuvent utiliser l’API pour améliorer l’efficacité des campagnes publicitaires.

Pour commencer à utiliser l’API de sélection d’annonces et tester le flux de bout en bout, inscrivez-vous à la préversion limitée de l’API sélection d’annonces.

En tant que vendeur exploitant une plateforme côté offre ou acheteur exploitant une plateforme côté demande, utilisez ce guide pour :

  • Inscrivez-vous à la préversion limitée de l’API sélection d’annonces en vous inscrivant à la version d’évaluation d’origine.
  • Terminez l’attestation d’API en publiant votre fichier JSON d’attestations.
  • Configurez un environnement d’évaluation avec un fournisseur de cloud pris en charge.
  • Consultez la documentation de l’API sélection d’annonces.
  • Préparez vos fonctions User-Defined (UDF).
  • Déployez vos services sur Azure.
  • Testez l’API de sélection d’annonces sur votre site.

Inscription d’attestation et inscription alpha

Quand et où la préversion est-elle disponible ?

Les versions de Microsoft Edge à compter de 130.0.2808.0 prennent en charge l’API de sélection d’annonces dans une préversion limitée pour les développeurs en dehors de l’Espace économique européen (EEE) et du Royaume-Uni (Royaume-Uni).

Indicateurs de test

Pour modifier les fonctionnalités de la plateforme de l’API sélection d’annonces sur votre ordinateur de développeur, utilisez les indicateurs de test de l’API sélection d’annonces à l’adresse edge://flags#edge-ad-selection-api:

Indicateurs « API de sélection d’annonces »

L’indicateur API Sélection d’annonces active l’API de sélection d’annonces et les fonctionnalités associées telles que :

  • Rapports d’attribution.
  • Cadres clôturés.
  • Stockage partagé.
  • Agrégation privée.

Exigences et processus d’inscription et d’attestation

Les développeurs intéressés par les tests alpha peuvent rejoindre la version d’évaluation d’origine pour l’API de sélection d’annonces. Cet essai d’origine permet de tester de bout en bout les fonctionnalités de l’API de sélection d’annonces, couvrant à la fois l’utilisation de l’API et le déploiement d’images conteneur sécurisées.

Pour chaque domaine de niveau supérieur que vous envisagez d’utiliser avec l’API Sélection d’annonces, remplissez le formulaire d’inscription à la version d’évaluation d’Origin pour ce domaine, puis envoyez le formulaire.

Pour vous inscrire à l’essai d’origine de l’API Sélection d’annonces pour un domaine :

  1. Ouvrez l’inscription à l’essai de l’API Sélection d’annonces dans Microsoft Edge dans une nouvelle fenêtre ou un nouvel onglet.

  2. Cliquez sur le bouton Démarrer maintenant .

  3. Lisez et acceptez les conditions d’utilisation, puis cliquez sur le bouton Suivant . Le formulaire d’inscription à la version d’évaluation de l’API De sélection d’annonces s’ouvre :

    Formulaire d’inscription

  4. Dans la zone de texte Domaine , entrez un seul domaine de niveau supérieur :

    Vous pouvez configurer la version d’évaluation d’origine pour prendre en charge l’un des éléments suivants :

    • Un seul domaine, tel que https://example.com, sans prendre en charge ses sous-domaines.
    • Un sous-domaine unique, tel que https://beta.example.com.
    • Un domaine, tel que https://example.com, et ses sous-domaines, tels que https://beta.example.com.

    Les chemins de fin et les paramètres de requête ne sont pas pris en charge. Si un URI est entré qui a un chemin de fin ou un paramètre de requête, tel que https://example.com/path/new-feature, le domaine racine (tel que https://example.com) ou le sous-domaine est inscrit, ignorant tout chemin de fin ou tout paramètre de requête.

  5. Dans la section Prise en charge du sous-domaine , sélectionnez le bouton d’option Oui ou Non :

    • Pour utiliser la version d’évaluation d’origine sur un domaine (tel que https://example.com) sans prendre en charge ses sous-domaines (par exemple https://beta.example.com), sélectionnez Non.
    • Pour utiliser la version d’évaluation d’origine uniquement sur un sous-domaine spécifique (par https://beta.example.comexemple), sélectionnez Non.
    • Pour utiliser la version d’évaluation d’origine sur un domaine (tel que https://example.com) et ses sous-domaines (tels que https://beta.example.com), sélectionnez Oui.

  6. Dans la zone de texte Adresse Email, indiquez un contact développeur valide pour le domaine.

  7. Cliquez sur le bouton Envoyer .

    Un jeton d’essai d’origine est généré pour le domaine de niveau supérieur et vous est envoyé.

  8. Créez un fichier nommé ad-selection-attestations.jsonet hébergez le fichier dans le domaine de niveau supérieur, dans le /.well-known/ répertoire . Par exemple :

    https://contoso.example/.well-known/ad-selection-attestations.json

    Le ad-selection-attestations.json fichier doit être publié dans les 30 jours suivant la réception du jeton OT. L’hébergement de ce fichier JSON est nécessaire pour terminer votre attestation et permettre à votre code d’accéder à l’API de sélection d’annonces, afin de tester l’API de sélection d’annonces avec les clients Microsoft Edge pris en charge.

Exemple de fichier JSON

Le fichier JSON d’attestations doit être nommé ad-selection-attestations.jsonet doit être conforme aux normes suivantes ci-dessous. Voici un exemple de ad-selection-attestations.json fichier :

{
    "ad_selection_api_attestations": [
        {
            "attestation_parser_version": "2",
            "attestation_version": "2",
            "privacy_policy": [
                "https://contoso.example/privacy/"
            ],
            "ownership_token": "<Your Unique Token Here>",
            "enrollment_site": "https://contoso.example/",
            "platform_attestations": [
                {
                    "platform": "edge",
                    "attestations": {
                        "ad_selection_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "attribution_reporting_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "shared_storage_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        },
                        "private_aggregation_api": {
                            "ServiceNotUsedForIdentifyingUserAcrossSites": true/false
                        }
                    }
                },
                {
                    "platform": "android",
                    "attestations": {}
                }
            ]
        }
    ]
}
Champs et valeurs importants

  • Le ad-selection-attestations.json fichier doit inclure le jeton d’essai d’origine qui vous a été généré et envoyé pour ce domaine de niveau supérieur. "ownership_token": est le jeton d’essai d’origine qui a été généré lors de l’inscription de ce domaine pour la version d’évaluation d’origine de l’API sélection d’annonces.

  • Dans la "platform_attestations": section , "platform": doit être "edge" ou "android".

  • Le fichier doit inclure une liste d’API (fonctionnalités associées à l’API Ad Services). Dans la "platform_attestations": section, les membres valides de "attestations": sont les suivants :

    • "ad_selection_api":- API main, pour la logique d’enchère privée.
    • "attribution_reporting_api": - Rapports d’attribution.
    • "shared_storage_api": - Stockage partagé.
    • "private_aggregation_api": - Agrégation privée.
    • Conditions préalables :
      • Chaque "..._api": entrée doit avoir un seul champ, "ServiceNotUsedForIdentifyingUserAcrossSites":, avec une true valeur ou false . true signifie que ce service n’est pas utilisé pour identifier l’utilisateur sur les sites. false signifie que ce service est utilisé pour identifier l’utilisateur sur les sites.

Déployer les services d’API sélection d’annonces

L’API de sélection d’annonces utilise un environnement d’exécution approuvé (TEE) pour fournir un niveau d’assurance pour l’intégrité des données, la confidentialité des données et l’intégrité du code . Consultez Informatique confidentielle : Hardware-Based exécution approuvée pour les applications et les données. Les services fournis par l’API de sélection d’annonces doivent s’exécuter dans un TEE pour sécuriser les données utilisées par ces services.

Les services de sélection d’annonces exécutés dans un TEE doivent être déployés sur une plateforme cloud qui prend en charge les fonctionnalités de sécurité nécessaires. Au départ, les services peuvent être déployés dans Azure à l’aide de conteneurs ACI confidentiels ; consultez Conteneurs confidentiels sur Azure Container Instances.

L’API sélection d’annonces fournit différents services qui doivent être déployés par les vendeurs ou les acheteurs.

Images pour le déploiement de services

Ajoutez vos fonctions User-Defined (UDF) dans les images de services fournies. Le User-Defined Functions peut exécuter une logique métier personnalisée. Les fonctions User-Defined s’exécutent dans des conteneurs privés au sein des services déployés.

Chaque image définit un service. Certaines images ne contiennent pas de fonctions définies par l’utilisateur et se composent entièrement de code prédéfini. Certaines images contiennent des fonctions définies par l’utilisateur, sous forme de fonctions avec un corps vide ou du code de démarrage, qui sont les fonctions User-Defined appropriées pour ce service. Renseignez les corps des fonctions User-Defined dans ces images avec votre propre code personnalisé.

Microsoft fournit une image pour chaque service, qui peut être déployée sur un fournisseur de cloud. Il s’agit des images publiques qui doivent être utilisées pour le déploiement. Seules les images officielles de Microsoft sont en mesure d’exécuter des enchères privées.

Images pour le déploiement :

Services pour les vendeurs

Service Description
SellerFrontEnd Fournit un /SelectAd point de terminaison HTTPS, qui reçoit des demandes du service publicitaire non approuvé du vendeur pour lancer le flux d’enchères Public protégé.
Vente aux enchères Fournit un /ScoreAds point de terminaison, qui reçoit les demandes du service SellerFrontEnd , contenant les enchères qui participent à l’enchère. Répond avec une valeur de score que le service SellerFrontEnd utilise pour choisir le gagnant.
Clé/Valeur Reçoit les demandes du service SellerFrontEnd , qui contiennent des clés de recherche provenant des enchères des acheteurs (telles que ad_render_urls). Retourne les signaux de scoring en temps réel qui sont requis pour l’enchère. S’exécute en mode BYOS (Bring Your Own Service), le vendeur n’a donc pas besoin de déployer ce service dans un environnement d’exécution approuvé (TEE) et peut utiliser à la place l’image fournie par Microsoft.

Services pour les acheteurs

Service Description
BuyerFrontEnd Fournit un /GetBids point de terminaison qui reçoit des demandes du service SellerFrontEnd pour lancer le flux d’enchères.
Enchères Fournit un /GenerateBids point de terminaison qui reçoit des demandes du service BuyerFrontEnd pour gérer l’enchère et générer une enchère. Génère une enchère, choisit le gagnant et sélectionne la bannière à afficher.
Clé/Valeur Reçoit les demandes du service BuyerFrontEnd et retourne les données d’acheteur en temps réel requises pour les enchères, correspondant aux clés de recherche des Groupes d’intérêt. Une telle requête se produit une seule fois par workflow. S’exécute en mode BYOS (Bring Your Own Service).
Sélection des enchères & clé/valeur Reçoit des demandes du service Enchères pour sélectionner et retourner des bannières publicitaires supplémentaires (candidats) qui peuvent participer aux enchères. Le service De sélection des enchères & clé/valeur peut également retourner des signaux supplémentaires nécessaires à l’appel d’offres. Le service d’enchères peut envoyer plusieurs demandes au service De sélection des enchères & clé/valeur , ou choisir de ne pas envoyer de demandes, car le service Sélection des enchères & clé/valeur est facultatif. Le service De sélection des enchères & clé/valeur doit être déployé dans un environnement d’exécution approuvé (TEE).
K-Anonymat Collecte les compteurs k-anonymat et vérifie que la publicité gagnante créatif passe le k-anonymat case activée.

Fonctions définies par l’utilisateur

Les vendeurs et les acheteurs doivent fournir leur propre code personnalisé en tant que fonctions User-Defined (UDF) qui s’exécutent dans des conteneurs privés au sein des services déployés. Ces User-Defined Functions peuvent exécuter une logique métier personnalisée.

Chaque acheteur ou vendeur peut déployer plusieurs instances d’un service donné, par exemple :

  • SellerFrontEnd et Auction.
  • BuyerFrontend, Enchère et K-Anonymat.

Certains de ces services prennent une entrée qui est un worklet JavaScript qui définit User-Defined Functions.

User-Defined Functions pour les vendeurs
Fonction définie par l’utilisateur Service dans lequel la fonction définie par l’utilisateur s’exécute Description
scoreAd() Vente aux enchères Génère un score pour l’offre de chaque acheteur, ou rejette l’offre. Ce score est ensuite utilisé par le service SellerFrontEnd pour choisir un gagnant parmi tous les acheteurs.
reportResult() SellerFrontEnd Pour les rapports au niveau des événements. S’exécute dans le service SellerFrontEnd une fois que le gagnant final a été choisi. Informe le vendeur du soumissionnaire gagnant et fournit la valeur de l’offre.
User-Defined Functions pour les acheteurs
Fonction définie par l’utilisateur Service dans lequel la fonction définie par l’utilisateur s’exécute Description
generateBids() Enchères Génère une enchère et choisit la bannière qui sera affichée.
reportWin() SellerFrontEnd Pour les rapports au niveau des événements. S’exécute dans le service SellerFrontEnd , si l’offre de l’acheteur remporte la vente aux enchères. Avertit l’acheteur qu’il a gagné l’enchère et génère des URL de notification qui seront déclenchées ultérieurement, par exemple pendant le rendu de bannière ou d’autres événements clients.
getValues() Sélection des enchères & clé/valeur S’exécute dans le service Sélection des enchères & clé/valeur , si l’acheteur utilise ce service. Autorise l’exécution de code personnalisé pour la recherche et la sélection des données.

Guide de déploiement

Pour déployer le service d’API sélection d’annonces sur Azure :

  1. Créez un compte Azure et créez un abonnement sur Microsoft Azure.

  2. Choisissez l’option Conteneurs ACO confidentiels .

  3. Accédez à Scripts de déploiement Terraform dans une nouvelle fenêtre ou un nouvel onglet, puis téléchargez les scripts de déploiement Terraform et consultez la documentation de déploiement. Note: Assurez-vous que le hachage de l’image que vous avez téléchargée correspond au hachage dans le script que vous téléchargez.

  4. Les scripts Terraform incluent déjà des liens vers des images publiques fournies par Microsoft. Choisissez les services requis et déployez-les en suivant les étapes décrites dans le inclus readme.md.

    1. Définissez tous les indicateurs spécifiques pour votre environnement, y compris les emplacements de worklet d’enchères.

    2. Configurez toutes les conditions préalables et préparez tous les outils pour le déploiement.

    3. Créez des ressources Azure et exécutez le script Terraform qui termine le déploiement.

  5. Développez des worklets, y compris user-defined-function (UDF) et démarrez les services d’API sélection d’annonces.

Utiliser l’API de sélection d’annonces sur votre site web

Pour commencer à utiliser l’API de sélection d’annonces, les vendeurs et les acheteurs doivent modifier le code JavaScript de leurs sites web exécuté lorsque le navigateur est Microsoft Edge.

  • Vendeurs : Pour exécuter des enchères privées, récupérer des groupes d’intérêt et faire des rapports, mettez à jour votre code sur les sites web des éditeurs.

  • Acheteurs : Pour créer des groupes d’intérêt et les stocker dans le navigateur, mettez à jour le code sur les sites web de vos partenaires publicitaires. Vous pouvez utiliser le mécanisme de délégation pour restreindre et autoriser la création de groupes d’intérêts sur des domaines tiers.

Pour en savoir plus sur les méthodes d’API disponibles et pour afficher un exemple de code, consultez Détails de l’API sélection d’annonces.

Fournir des commentaires sur l’essai d’origine

Pour fournir des commentaires sur l’essai d’origine de l’API sélection d’annonces, créez un problème sur le dépôt GitHub WICG/privacy-preserveing-ads :

Voir aussi

Essais d’origine :

Documents techniques et de conception :

Images pour le déploiement :

Scripts de déploiement :

Environnement d’exécution approuvé (TEE) :

Azur: