Key-Values Google Ad Manager :
Le Guide Ultime des Limites & API

Comprendre les types : Predefined vs Free-form

Google Ad Manager propose deux types de clés de ciblage. Le choix entre ces deux types influence la manière dont vous insérez les données par API et dont elles apparaissent dans vos rapports :

• Predefined (Pré-définies) : Vous devez déclarer à l'avance toutes les valeurs possibles de la clé dans la console GAM ou par API avant de pouvoir les cibler. Exemple typique : genre=femme,homme,autre. Les clés pré-définies sont idéales lorsque les valeurs sont fixes et stables. Elles apparaissent proprement dans les dimensions de reporting.
• Free-form (Libres) : Vous définissez la clé (ex: search_term), mais vous n'avez pas besoin d'enregistrer les valeurs à l'avance. Elles sont créées à la volée lorsque le tag publicitaire les transmet depuis le navigateur. Exemple typique : keywords=chaussures-running. Pratique pour les valeurs dynamiques ou les gros catalogues.

Les Limites Techniques à connaître absolument

L'API Google Ad Manager renvoie des erreurs bloquantes ou tronque silencieusement vos requêtes si vous dépassez les contraintes suivantes :

Key-Values Recommandées par type d'inventaire

Pour structurer efficacement vos campagnes publicitaires directes ou programmatiques, voici les clés indispensables à mettre en place selon votre modèle d'affaires :

Gestion simplifiée via le plugin MCP OrbiAds

Plus besoin d'ouvrir l'interface complexe de GAM pour créer vos clés de ciblage ou vos valeurs. Le plugin MCP OrbiAds expose des outils d'écriture directs pour vos agents IA ou scripts locaux.

Étape 1 : Créer la clé de ciblage

# In Claude — OrbiAds MCP plugin
create_custom_targeting_key(
  name="pos",
  display_name="Position sur la page",
  key_type="PREDEFINED",
  reportable_type="ON",
  dry_run=false
)

Étape 2 : Ajouter des valeurs à une clé existante (indispensable pour les clés de type PREDEFINED) :

# Append values to the targeting key (ID returned from Step 1)
create_custom_targeting_values(
  key_id="12984572",
  values=[
    {"name": "atf", "displayName": "Above the Fold"},
    {"name": "btf", "displayName": "Below the Fold"}
  ],
  dry_run=false
)

Explorateur Admin : Suivi rapide et Visuel

Pour les utilisateurs connectés, OrbiAds propose une interface d'exploration visuelle rapide de toutes vos Key-Values directement dans votre panel d'administration sous la route :

Cet explorateur affiche en temps réel les clés actives de votre réseau publicitaire Google Ad Manager, le nombre de valeurs enregistrées, et vous permet de déplier les valeurs au format mono pour vérifier l'exactitude des variables.

Code d'intégration : Du Backend API au Frontend GPT

Voici comment créer une clé de ciblage côté serveur avec le SDK Python SOAP officiel, puis comment la cibler côté client dans le navigateur avec Google Publisher Tag (GPT).

1. Création de Key-Value en Python (SOAP SDK)

from googleads import ad_manager

# Initialiser le client Ad Manager
client = ad_manager.AdManagerClient.LoadFromStorage()
custom_targeting_service = client.GetService(
    'CustomTargetingService', version='v202602'
)

# Déclarer une clé de ciblage "freeform"
key = {
    'name': 'consent_status',
    'displayName': 'Consent status (GDPR)',
    'type': 'FREEFORM'
}

keys = custom_targeting_service.createCustomTargetingKeys([key])
print(f"Clé créée avec l'ID: {keys[0]['id']}")

2. Ciblage côté client (JavaScript GPT)

Une fois la clé créée, transmettez-la dans le header de votre site web pour alimenter vos Line Items :

window.googletag = window.googletag || { cmd: [] };
window.googletag.cmd.push(function () {
  // Ciblage au niveau de la page entière
  window.googletag.pubads().setTargeting('section', 'tech');
  window.googletag.pubads().setTargeting('consent', '1');

  // Ciblage spécifique sur un slot publicitaire particulier
  window.googletag.defineSlot('/1234/site/banner', [300, 250], 'div-gpt-ad')
    .setTargeting('pos', 'atf')
    .addService(window.googletag.pubads());
});

Bonnes Pratiques de robustesse

• Attention aux majuscules : GPT convertit automatiquement les valeurs ciblées en minuscules. N'insérez jamais de valeurs contenant des majuscules par API sous peine de casser l'association de ciblage.
• Throttling API : Les modifications massives de Key-Values via l'API SOAP déclenchent rapidement des exceptions QuotaError.EXCEEDED_QUOTA. Implémentez un délai d'attente exponentiel (exponential backoff) de 500 ms minimum entre chaque lot d'appels.

Démarrer l'automatisation de ciblage

Exploitez le plugin MCP d'OrbiAds pour auditer et peupler instantanément vos structures de ciblage de campagnes. En quelques instructions, vos environnements sont harmonisés.