Format d'annonce du SDK de l'acheteur

Les annonces avec SDK de l'acheteur utilisent des créations affichées par votre propre SDK.

L'inventaire d'applications mobiles des éditeurs qui intègrent votre adaptateur d'enchères dans leur application peut accepter les enchères avec le format d'annonce affiché par le SDK de l'acheteur. Leur affichage dépend de l'implémentation du SDK et de l'SDKRenderedAd que vous envoyez dans la réponse à l'enchère.

Vous pouvez placer une enchère incluant une annonce affichée par un SDK d'acheteur ou tout autre format d'annonce compatible avec le SDK Google Mobile Ads, mais toutes les enchères contenant les deux sont filtrées.

Conditions requises

Les annonces SDK d'acheteur sont disponibles pour les acheteurs approuvés. Ce format nécessite un effort supplémentaire de votre part et de celle de l'éditeur. Contactez votre responsable de compte technique pour configurer votre compte pour les annonces SDK d'acheteur. Vous pouvez ensuite implémenter un adaptateur d'enchères qui permet à votre SDK de communiquer avec le SDK Google Mobile Ads. L'éditeur doit intégrer votre SDK et votre adaptateur dans ses applications mobiles.

Nous vous recommandons d'envoyer vos créations pour examen avant de les inclure dans une réponse aux enchères. Contactez votre responsable de compte technique si vous ne connaissez pas le type de création au moment de l'enchère.

Si une demande d'enchère est compatible avec ce format d'annonce, vous pouvez spécifier une annonce qui s'affiche avec votre SDK en définissant le champ sdk_rendered_ad dans la réponse aux enchères.

Demande d'enchère

Les demandes d'enchères pour l'inventaire d'applications mobiles incluent des informations sur les SDK et les adaptateurs de l'application de l'éditeur que vous pouvez utiliser pour l'affichage dans les champs suivants :

ID du SDK

Vous pouvez utiliser la demande d'enchère pour trouver l'ID du SDK que vous devez fournir dans la réponse aux enchères avec le champ BidRequest.app.ext.installed_sdk.id.

Pour en savoir plus, consultez la documentation de référence sur InstalledSdk.

Mappage des blocs d'annonces

Vous pouvez utiliser la demande d'enchères pour trouver les mappages de blocs d'annonces qui correspondent à l'emplacement d'annonce avec le champ BidRequest.imp.ext.ad_unit_mapping.

Pour en savoir plus, consultez la documentation de référence sur AdUnitMapping.

Signaux sécurisés

Les éditeurs peuvent partager des signaux sécurisés avec les enchérisseurs. Vous les trouverez dans BidRequest.imp.ext.buyer_generated_request_data.data.

Pour en savoir plus sur la façon dont les signaux sécurisés sont représentés, consultez la documentation de référence sur BuyerGeneratedRequestData.

Demandes de tests

Vous pouvez utiliser le champ BidRequest.test pour vérifier si la demande d'enchère est un test.

Pour en savoir plus sur ce champ, consultez la documentation de référence sur BidRequest.

Exemple de demande d'enchère

id: "<bid_request_id>"
imp {
  id: "1"
  banner {
    w: 320
    h: 50
    ...
  }
...
  adx_ext {
   ...
    ad_unit_mapping {
      keyvals {
        key: "key_1"
        value: "value_1"
      }
      keyvals {
        key: "key_2"
        value: "value_2"
      }
      ...
      format: FORMAT_BANNER
    }
  }
}
app {
 ...
  adx_ext {
    installed_sdk {
      id: "com.google.ads.mediation.partner.PartnerMediationAdapter"
      sdk_version {
        major: 1
        minor: 2
        micro: 30
      }
      adapter_version {
        major: 1
        minor: 2
        micro: 3000
      }
    }
    installed_sdk {
    ...
    }
    ...
  }
}
device {
  ...
}
user {
  ...
  }
  adx_ext {
    eids {
      source: "com.google.ads.mediation.partner.PartnerMediationAdapter"
      uids {
        id: "<partner_signal_string>"
      }
    }
  }
}
at: 1
tmax: 1000
cur: "USD"
test: 1
...
adx_ext {
  google_query_id: "<query_string>"
  ...
}

Réponse à l'enchère

Important : Les acheteurs doivent toujours se référer à ce document pour déterminer les champs requis pour les enchères SDK. Certains champs requis pour les enchères SDK peuvent être marqués comme facultatifs dans le guide d'intégration OpenRTB.

Les champs suivants sont obligatoires dans la réponse à l'enchère :

• BidResponse.seatbid.bid.adomain
• BidResponse.seatbid.bid.ext.billing_id
• BidResponse.seatbid.bid.crid
• BidResponse.seatbid.bid.w
• BidResponse.seatbid.bid.h

De plus, votre réponse aux enchères doit remplir BidResponse.seatbid.bid.ext.sdk_rendered_ad avec les éléments suivants :

ID du SDK

Utilisez le champ id pour fournir l'ID permettant au SDK d'afficher l'annonce.

Vous trouverez l'ID dans BidRequest.app.ext.installed_sdk.

Annonce déclarée

Utilisez BidResponse.seatbid.bid.ext.sdk_rendered_ad.declared_ad pour fournir une création qui répond aux exigences de BidRequest.imp.ext.creative_enforcement_settings et qui est représentative des données de rendu de l'annonce. Un seul des champs html_snippet, video_url, video_vast_xml ou native_response doit être renseigné.

Si vous ne renseignez pas declared_ad, nous ne pourrons pas examiner la création et toutes les enchères associées seront filtrées de l'enchère.

Pour en savoir plus sur l'annonce déclarée, consultez la documentation de référence sur DeclaredAd.

Afficher les données

Utilisez le champ BidResponse.seatbid.bid.ext.sdk_rendered_ad.rendering_data pour fournir les données que le SDK de l'acheteur utilisera pour afficher votre annonce.

Les enchères pour diffuser une annonce SDK d'acheteur doivent spécifier une création dans le champ declared_ad. L'annonce déclarée doit représenter précisément le rendering_data.

Voici un exemple d'objet SdkRenderedAd :

{
  "id": "1234567",
  "rendering_data": "\xd58...,\xd4\x89\xd\xf9",
  "declared_ad": {
    "html_snippet": "<iframe src=\"https://example.com/ads?id=123&
      curl=%%CLICK_URL_ESC%%&wprice=%%WINNING_PRICE_ESC%%\"></iframe>",
  }
}

Nous vous recommandons d'utiliser l'API Real-time Bidding pour envoyer des créations à examiner avant de les inclure dans une réponse aux enchères.

Pour en savoir plus sur les champs SdkRenderedAd, consultez le guide OpenRTB.

Exemple de réponse à l'enchère

Voici des exemples de réponses aux enchères pour chaque format d'annonce :

Bannière

id: "<bid_request_id>"
seatbid {
  bid {
    id: "<bidder_generated_response_id>"
    impid: "1"
    price: 99
    adomain: "https://play.google.com/store/apps/details?id=com.test.app"
    cid: "<billing_id>"
    crid: "<creative_id>"
    w: 320
    h: 50
    burl: "https://abc.com/billing?td=fn&win_price=${AUCTION_PRICE}"
    adx_ext {
      sdk_rendered_ad {
        id: "com.google.ads.mediation.partner.PartnerMediationAdapter"
        rendering_data: "<rendering_data_string>"
        declared_ad {
          click_through_url: "https://play.google.com/store/apps/details?id=com.test.app"
          html_snippet: "<!doctype html> <html> ... </html>"
        }
      }
      event_notification_token {
        payload: "<payload_string>"
      }
      billing_id: 141763360450
    }
  }
}
bidid: "<bidder_generated_response_id>"
cur: "USD"

Interstitiel

id: "<bid_request_id>"
seatbid {
  bid {
    id: "<bidder_generated_response_id>"
    impid: "1"
    price: 400
    adomain: "https://play.google.com/store/apps/details?id=com.test.app"
    cid: "<billing_id>"
    crid: "<creative_id>"
    w: 412
    h: 775
    adx_ext {
      sdk_rendered_ad {
        id: "com.google.ads.mediation.partner.PartnerMediationAdapter"
        rendering_data: "<rendering_data_string>"
        declared_ad {
          click_through_url: "https://play.google.com/store/apps/details?id=com.test.app"
          video_vast_xml: "<VAST version=\"2.0\"><Ad>...</Ad></VAST>"
        }
      }
      event_notification_token {
        payload: "<payload_string>"
      }
    }
  }
}
bidid: "<bidder_generated_response_id>"
cur: "USD"

Annonce vidéo avec récompense

id: "<bid_request_id>"
seatbid {
  bid {
    id: "<bidder_generated_response_id>"
    impid: "1"
    price: 400
    adomain: "https://play.google.com/store/apps/details?id=com.test.app"
    cid: "<billing_id>"
    crid: "<creative_id>"
    w: 412
    h: 775
    adx_ext {
      sdk_rendered_ad {
        id: "com.google.ads.mediation.partner.PartnerMediationAdapter"
        rendering_data: "<rendering_data_string>"
        declared_ad {
          click_through_url: "https://play.google.com/store/apps/details?id=com.test.app"
          video_vast_xml: "<VAST version=\"2.0\"><Ad>...</Ad></VAST>"
        }
      }
      event_notification_token {
        payload: "<payload_string>"
      }
    }
  }
}
bidid: "<bidder_generated_response_id>"
cur: "USD"

Natif

id: "<bid_request_id>"
seatbid {
  bid {
    id: "<bidder_generated_response_id>"
    impid: "1"
    price: 400
    adomain: "https://play.google.com/store/apps/details?id=com.test.app"
    cid: "<billing_id>"
    crid: "<creative_id>"
    w: 1200
    h: 627
    adx_ext {
      sdk_rendered_ad {
        id: "com.google.ads.mediation.partner.PartnerMediationAdapter"
        rendering_data: "<rendering_data_string>"
        declared_ad {
          click_through_url: "https://play.google.com/store/apps/details?id=com.test.app"
          native_response {
            ...
            assets {
              id: 1
              title {
                text: ""
              }
            }
            assets {
              id: 2
              data {
                value: "<some_string>"
              }
            }
            assets {
              id: 3
              data {
                value: "View now"
              }
            }
            assets {
              id: 4
              img {
                url: "<valid_image_url>"
                w: 1200
                h: 627
                type: 3
              }
            }
            assets {
              id: 5
              img {
                url: "<valid_image_url>"
                w: 100
                h: 100
                type: 1
              }
            }
            assets {
              id: 6
              data {
                value: ""
              }
            }
            assets {
              id: 7
              data {
                value: "<some_string>"
              }
            }
            link {
              url: "<destination_link>"
            }
          }
        }
      }
      event_notification_token {
        payload: "<payload_string>"
      }
    }
  }
}
bidid: "<bidder_generated_response_id>"
cur: "USD"

Examen des créations

Les créations sont examinées avant de pouvoir être diffusées afin de vérifier qu'elles respectent nos Règles et les paramètres des éditeurs.

Avertissement : Les créations qui n'ont pas été examinées sont filtrées et exclues de la mise aux enchères.

Voici deux façons d'envoyer des créations pour examen :

API Real-time Bidding (recommandée)

Vous pouvez utiliser la méthode buyers.creatives.create de l'API Real-time Bidding pour envoyer des créations à examiner.

L'API ne nécessite qu'un seul envoi par création et vous permet de vérifier l'état de l'examen de votre création.

Réponse à l'enchère

Vous pouvez envoyer de nouvelles créations directement dans la réponse à l'enchère.

Vous devez utiliser le champ declared_ad de l'objet SdkRenderedAd pour envoyer une réponse aux enchères avec une création de SDK d'acheteur à examiner.

Les créations envoyées dans la réponse aux enchères ne sont examinées qu'après de nombreuses enchères. Toutes les enchères placées avant la fin de l'examen sont filtrées et ne participent pas aux enchères. Vous pouvez utiliser l'interface Real-time Bidding ou l'API Real-time Bidding pour vérifier l'état d'une création une fois l'examen commencé.

Pour en savoir plus, consultez le guide sur les créations.