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

La réponse courte

Une key-value GAM est une paire clé=valeur envoyée dans la requête publicitaire (via GPT) et ciblée dans vos line items. Selon le Help Center Google : 40 caractères maximum par valeur, 20 par clé (la référence SOAP indique 10, donc gardez vos clés sous 10 caractères), 200 clés actives et 100 000 valeurs actives par clé par réseau. Chaque paire ciblée compte pour 1 des 800 critères d'un line item. Clés et valeurs ne sont pas sensibles à la casse, et une clé ne peut pas contenir d'espace.

Comprendre les types : predefined vs dynamic (free-form)

La console parle de clés « predefined » et « dynamic » ; l'API SOAP expose le même choix dans CustomTargetingKey.type avec les valeurs PREDEFINED et FREEFORM. Ce choix détermine comment les valeurs sont déclarées, et quels types de correspondance sont possibles :

• Predefined : vous définissez à l'avance les valeurs (console ou createCustomTargetingValues), et les traffickers les choisissent dans une liste. Exemple : gender=female,male,other. Idéal quand la plage de valeurs est connue et stable. Une clé sans valeur définie n'est pas diffusable.
• Dynamic (FREEFORM) : vous définissez la clé, mais les valeurs viennent du tag publicitaire et sont saisies au moment du ciblage. Exemple : pageid=123456. Utile pour les valeurs nombreuses ou changeantes. Les types de correspondance (BROAD, PREFIX…) ne s'appliquent qu'aux clés dynamic, et l'API les réserve aux réseaux Ad Manager 360.

Les limites à connaître

Chiffres issus de l'article « System maximums and limits » du Help Center Google Ad Manager. Votre réseau peut avoir des exceptions : vérifiez dans Admin > Paramètres globaux > Limites.

Convention de nommage recommandée

Le nom (name) est ce qui part dans l'URL de la requête publicitaire ; le nom d'affichage (displayName) n'est vu que par vos traffickers. Une convention stable évite les doublons et les erreurs de saisie :

• Noms courts en minuscules, sans espace, en snake_case si besoin : pos, section, prodcat. Visez 10 caractères ou moins pour les clés.
• Une dimension par clé : ne concaténez pas plusieurs informations dans une valeur (sports-atf). Deux clés, deux ciblages combinables.
• Le sens va dans le nom d'affichage : clé pos, nom d'affichage « Position sur la page ». Pour les valeurs aussi, un nom court et un nom d'affichage lisible.
• Plages en texte : 18-34, pas de comparateurs. Valeurs stables dans le temps, sans majuscules ni caractères réservés.
• Aucune donnée personnelle : Google interdit de transmettre des informations identifiantes (PII) ; n'utilisez jamais d'identifiant utilisateur comme valeur.
• Préfixe par source quand plusieurs systèmes écrivent des clés (hb_ pour Prebid) afin de ne jamais entrer en collision avec vos clés éditoriales.

Key-values recommandées par type d'inventaire

Points de départ courants selon votre modèle. Adaptez les noms à votre convention ; tous restent sous 10 caractères.

Création via le serveur MCP OrbiAds

Plus besoin de passer par la console GAM pour créer clés et valeurs : le serveur MCP OrbiAds expose ces écritures à vos agents IA via l'outil targeting. Toute écriture est en dry-run par défaut : vous relisez l'aperçu, puis vous confirmez.

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

# Dans Claude : serveur MCP OrbiAds (dry_run par défaut)
targeting(
  action="create_custom_targeting_key",
  params={
    "name": "pos",
    "displayName": "Position sur la page",
    "keyType": "PREDEFINED",
    "reportableType": "ON",
    "dryRun": True
  }
)

Étape 2 : ajouter des valeurs à la clé (indispensable pour une clé PREDEFINED) :

# L'ID de la clé est renvoyé à l'étape 1
targeting(
  action="create_custom_targeting_values",
  params={
    "keyId": "12984572",
    "values": [
      {"name": "atf", "displayName": "Au-dessus de la ligne de flottaison"},
      {"name": "btf", "displayName": "Sous la ligne de flottaison"}
    ],
    "dryRun": True
  }
)

Explorateur de ciblage : vérifier ce qui existe

Pour les utilisateurs connectés, OrbiAds propose une vue d'exploration de vos key-values dans l'espace d'administration :

Consultez les clés et leurs valeurs avant de créer quoi que ce soit : cela évite les doublons (pos et position) et les fautes de frappe dans les valeurs.

Code d'intégration : de l'API SOAP au tag GPT

Voici comment créer une clé puis ses valeurs côté serveur avec la bibliothèque Python officielle googleads, puis comment transmettre ces key-values dans le navigateur avec Google Publisher Tag (GPT).

1. Création de key-values en Python (API SOAP)

from googleads import ad_manager

# Identifiants lus depuis googleads.yaml
client = ad_manager.AdManagerClient.LoadFromStorage()
service = client.GetService('CustomTargetingService', version='v202608')

# Clé predefined, reportable (name : 10 caractères max)
keys = service.createCustomTargetingKeys([{
    'name': 'pos',
    'displayName': "Position sur la page",
    'type': 'PREDEFINED',
    'reportableType': 'ON',
}])
key_id = keys[0]['id']

# Valeurs : matchType EXACT obligatoire sur une clé predefined
values = service.createCustomTargetingValues([
    {'customTargetingKeyId': key_id, 'name': 'atf',
     'displayName': "Au-dessus de la ligne de flottaison", 'matchType': 'EXACT'},
    {'customTargetingKeyId': key_id, 'name': 'btf',
     'displayName': "Sous la ligne de flottaison", 'matchType': 'EXACT'},
])

# Relecture : le filtre customTargetingKeyId est obligatoire
statement = (ad_manager.StatementBuilder(version='v202608')
             .Where('customTargetingKeyId = :keyId')
             .WithBindVariable('keyId', key_id))
response = service.getCustomTargetingValuesByStatement(statement.ToStatement())
for value in response.get('results', []):
    print(value['id'], value['name'])

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

Une fois les key-values créées, le tag doit les transmettre avec exactement les mêmes noms. Le ciblage défini sur un slot l'emporte sur celui défini pour la page. setTargeting() est désormais déprécié dans GPT au profit de setConfig() avec l'option targeting.

window.googletag = window.googletag || { cmd: [] };
googletag.cmd.push(function () {
  // Ciblage au niveau de la page (tous les slots)
  googletag.setConfig({ targeting: { section: 'tech', consent: '1' } });

  // Ciblage propre à un slot (plusieurs valeurs possibles avec un tableau)
  googletag
    .defineSlot('/1234/site/banner', [300, 250], 'div-gpt-ad')
    .addService(googletag.pubads())
    .setConfig({ targeting: { pos: 'atf' } });

  googletag.enableServices();
  googletag.display('div-gpt-ad');
});

Checklist de validation avant de pousser des line items

• Nom de clé : 10 caractères ou moins, sans espace, sans caractère réservé, ne commence pas par un chiffre.
• Valeurs : 40 caractères max, plages écrites en texte (18-34), aucune donnée personnelle.
• Type choisi d'emblée : predefined si vous connaissez les valeurs, dynamic sinon. Côté OrbiAds, le type d'une clé n'est pas modifiable après création.
• Valeurs définies pour toute clé predefined : une clé sans valeur n'est pas diffusable.
• Reporting décidé avant la mise en ligne : une clé n'apparaît dans les rapports qu'à partir du moment où elle est reportable.
• Tag vérifié : les noms envoyés par GPT correspondent exactement à ceux de GAM ; le nom figure dans l'URL de la requête publicitaire, vous pouvez l'y contrôler.
• Budget de critères : moins de 800 critères par line item, chaque paire clé-valeur comptant pour un.
• Dry-run relu via MCP avant confirmation, et premier test sur un ordre à faible trafic.

Erreurs fréquentes

• Clé ou valeur trop longue, caractère réservé : l'API renvoie CustomTargetingError.KEY_NAME_INVALID_LENGTH ou VALUE_NAME_INVALID_LENGTH, et KEY_NAME_INVALID_CHARS ou VALUE_NAME_INVALID_CHARS pour les caractères interdits.
• Type de correspondance non exact : les valeurs d'une clé predefined doivent être EXACT, et seuls les réseaux Ad Manager 360 acceptent un autre matchType (VALUE_MATCH_TYPE_NOT_ALLOWED, VALUE_MATCH_TYPE_NOT_EXACT_FOR_PREDEFINED_KEY). SUFFIX et CONTAINS sont refusés dans le ciblage d'un line item.
• Confondre nom et nom d'affichage : c'est le nom qui circule dans le tag. Saisir le nom d'affichage dans une expression avancée ne correspondra à rien.
• Activer le reporting trop tard : les rapports sur des dates antérieures à l'activation n'affichent rien pour cette clé.
• Quota API : en cas de QuotaError.EXCEEDED_QUOTA, Google recommande d'attendre environ 5 secondes avant de réessayer (et d'allonger le délai si l'erreur persiste), ou de limiter les requêtes à 2 par seconde (8 en Ad Manager 360).

Questions fréquentes sur les key-values GAM

Quelle est la limite de caractères des key-values Google Ad Manager ?

Le Help Center indique 20 caractères maximum par clé et 40 par valeur. La référence SOAP de CustomTargetingKey.name mentionne toutefois 10 caractères : pour les clés créées par API, restez à 10 caractères ou moins. Clés et valeurs ne sont pas sensibles à la casse, et les caractères " ' = ! + # * ~ ; ^ ( ) < > [ ] , & sont réservés.

Combien de key-values un line item peut-il cibler ?

Chaque paire clé-valeur compte pour un critère de ciblage, et un line item accepte jusqu’à 800 critères (inventaire, géographie, jour/heure et key-values confondus). Les 20 paires que vous avez peut-être lues concernent uniquement le ciblage des styles natifs.

Quelle différence entre key-values predefined et dynamic (FREEFORM dans l’API) ?

Les clés predefined ont des valeurs définies à l’avance que les traffickers choisissent dans une liste. Les clés dynamic prennent des valeurs issues du tag, sans définition préalable. Dans l’API SOAP, le champ CustomTargetingKey.type vaut PREDEFINED ou FREEFORM. Les types de correspondance (BROAD, PREFIX…) ne s’appliquent qu’aux clés dynamic.

Les key-values apparaissent-elles dans les rapports ?

Seules les clés marquées reportable (reportableType ON ou CUSTOM_DIMENSION) sont incluses, et seulement à partir du moment où elles le deviennent : les rapports sur des dates antérieures n’affichent rien. Les valeurs non définies n’apparaissent pas, même si la clé est reportable. Limites : 30 000 key-values reportables, 20 000 pour les dimensions personnalisées (Ad Manager 360).

Peut-on créer des key-values GAM depuis un agent IA ou un script ?

Oui. Avec le serveur MCP OrbiAds, un agent appelle l’outil targeting avec l’action create_custom_targeting_key pour déclarer une clé, puis create_custom_targeting_values pour ajouter des valeurs. Les écritures sont en dry-run par défaut : vous validez l’aperçu avant exécution. En script, utilisez createCustomTargetingKeys et createCustomTargetingValues de l’API SOAP.

Sources

Help Center Google Ad Manager : « System maximums and limits », « Valid key-value entry », « Predefined and dynamic key-values », « Names versus display names ». Référence API SOAP CustomTargetingService (v202608), types CustomTargetingKey et CustomTargetingValue. Référence Google Publisher Tag : setConfig et l'option targeting.

Automatiser votre ciblage

Le serveur MCP d'OrbiAds permet à un agent IA d'auditer vos clés existantes et d'en créer de nouvelles avec aperçu avant écriture.