Share via

Gérer les campagnes publicitaires

  • Article

Utilisez ces méthodes dans l’API de promotions du Microsoft Store pour créer, modifier et obtenir des campagnes publicitaires promotionnelles pour votre application. Chaque campagne que vous créez à l’aide de cette méthode ne peut être associée qu’à une seule application.

Note Vous pouvez également créer et gérer des campagnes publicitaires à l’aide de l’Espace partenaires, et les campagnes que vous créez par programme sont accessibles dans l’Espace partenaires. Pour plus d’informations sur la gestion des campagnes publicitaires dans l’Espace partenaires, consultez Créer une campagne publicitaire pour votre application.

Lorsque vous utilisez ces méthodes pour créer ou mettre à jour une campagne, vous appelez généralement une ou plusieurs des méthodes suivantes pour gérer les lignes de distribution, les profils de ciblage et les créations associés à la campagne. Pour plus d’informations sur la relation entre les campagnes, les lignes de distribution, les profils de ciblage et les créations, consultez Exécuter des campagnes publicitaires à l’aide des services du Microsoft Store.

Prérequis

Pour utiliser ces méthodes, vous devez d’abord effectuer les opérations suivantes :

  • Si vous ne l’avez pas déjà fait, remplissez tous les prérequis pour l’API de promotions du Microsoft Store.

    Note Dans le cadre des conditions préalables, veillez à créer au moins une campagne publicitaire payante dans l’Espace partenaires et à ajouter au moins un instrument de paiement pour la campagne publicitaire dans l’Espace partenaires. Les lignes de livraison pour les campagnes publicitaires que vous créez à l’aide de cette API facturent automatiquement l’instrument de paiement par défaut choisi dans la page Campagnes publicitaires de l’Espace partenaires.

  • Obtenez un jeton d’accès Azure AD à utiliser dans l’en-tête de requête pour ces méthodes. Une fois que vous avez récupéré le jeton d’accès, vous avez 60 minutes pour l’utiliser avant qu’il n’expire. Une fois le jeton arrivé à expiration, vous pouvez en obtenir un nouveau.

Requête

Ces méthodes ont les URI suivants.

Type de méthode URI de demande Description
POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign Crée une campagne publicitaire.
PUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} Modifie la campagne publicitaire spécifiée par campaignId.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} Obtient la campagne publicitaire spécifiée par campaignId.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign Requêtes pour les campagnes publicitaires. Consultez la section Paramètres pour connaître les paramètres de requête pris en charge.
En-tête Type Description
Autorisation string Obligatoire. Jeton d’accès Azure AD sous la formeJeton> du porteur<.
ID de suivi GUID facultatif. ID qui effectue le suivi du flux d’appels.

 

Paramètres

La méthode GET pour interroger les campagnes publicitaires prend en charge les paramètres de requête facultatifs suivants.

Nom Type Description
skip int Le nombre de lignes à ignorer dans la requête. Utilisez ce paramètre pour parcourir des ensembles de données. Par exemple, fetch=10 et skip=0 récupère les 10 premières lignes de données, top=10 et skip=10 récupère les 10 lignes de données suivantes, et ainsi de suite.
fetch int Le nombre de lignes de données à renvoyer dans la requête.
campaignSetSortColumn string Classe les objets Campaign dans le corps de la réponse en fonction du champ spécifié. La syntaxe est CampaignSetSortColumn=field, où le paramètre field peut être l’une des chaînes suivantes :

  • id
  • createdDateTime

La valeur par défaut est createdDateTime.
isDescending Boolean Trie les objets Campaign dans le corps de la réponse dans l’ordre décroissant ou croissant.
storeProductId string Utilisez cette valeur pour renvoyer uniquement les campagnes publicitaires associées à l’application avec l’ID du Store spécifié. Un exemple d’ID store pour un produit est 9nblggh42cfd.
label string Utilisez cette valeur pour renvoyer uniquement les campagnes publicitaires qui incluent l’étiquette spécifiée dans l’objet Campaign .

Corps de la demande

Les méthodes POST et PUT nécessitent un corps de requête JSON avec les champs obligatoires d’un objet Campaign et tous les champs supplémentaires que vous souhaitez définir ou modifier.

Exemples de demande

L’exemple suivant montre comment appeler la méthode POST pour créer une campagne publicitaire.

POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign HTTP/1.1
Authorization: Bearer <your access token>

{
    "name": "Contoso App Campaign",
    "storeProductId": "9nblggh42cfd",
    "configuredStatus": "Active",
    "objective": "DriveInstalls",
    "type": "Community"
}

L’exemple suivant montre comment appeler la méthode GET pour récupérer une campagne publicitaire spécifique.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/31043481  HTTP/1.1
Authorization: Bearer <your access token>

L’exemple suivant montre comment appeler la méthode GET pour rechercher un ensemble de campagnes publicitaires, triées par date de création.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign?storeProductId=9nblggh42cfd&fetch=100&skip=0&campaignSetSortColumn=createdDateTime HTTP/1.1
Authorization: Bearer <your access token>

response

Ces méthodes retournent un corps de réponse JSON avec un ou plusieurs objets Campaign , en fonction de la méthode que vous avez appelée. L’exemple suivant illustre un corps de réponse pour la méthode GET pour une campagne spécifique.

{
    "Data": {
        "id": 31043481,
        "name": "Contoso App Campaign",
        "createdDate": "2017-01-17T10:12:15Z",
        "storeProductId": "9nblggh42cfd",
        "configuredStatus": "Active",
        "effectiveStatus": "Active",
        "effectiveStatusReasons": [
            "{\"ValidationStatusReasons\":null}"
        ],
        "labels": [],
        "objective": "DriveInstalls",
        "type": "Paid",
        "lines": [
            {
                "id": 31043476,
                "name": "Contoso App Campaign - Paid Line"
            }
        ]
    }
}

Objet de campagne

Les corps de requête et de réponse pour ces méthodes contiennent les champs suivants. Ce tableau indique quels champs sont en lecture seule (ce qui signifie qu’ils ne peuvent pas être modifiés dans la méthode PUT) et quels champs sont requis dans le corps de la demande pour la méthode POST.

Champ Type Description Lecture seule Default Obligatoire pour POST
id entier L’ID de la campagne publicitaire. Oui Non
name string Nom de la campagne publicitaire. Non Oui
configureStatus string L’une des valeurs suivantes qui spécifie le status de la campagne publicitaire spécifiée par le développeur :
  • Actif
  • Inactif
 Non Actif Oui
effectiveStatus string L’une des valeurs suivantes qui spécifie la status effective de la campagne publicitaire en fonction de la validation du système :
  • Actif
  • Inactif
  • Traitement
 Oui Non
effectiveStatusReasons tableau Une ou plusieurs des valeurs suivantes qui spécifient la raison de la status effective de la campagne publicitaire :
  • AdCreativesInactive
  • Échec de facturation
  • AdLinesInactive
  • ValidationFailed
  • Échec
 Oui Non
storeProductId string ID du Store pour l’application à laquelle cette campagne publicitaire est associée. Un exemple d’ID de magasin pour un produit est 9nblggh42cfd. Oui Oui
étiquettes tableau Une ou plusieurs chaînes qui représentent des étiquettes personnalisées pour la campagne. Ces étiquettes sont utilisées pour la recherche et l’étiquetage des campagnes. Non null Non
type string L’une des valeurs suivantes qui spécifie le type de campagne :
  • Payant
  • Maison
  • Communauté
 Oui Oui
objective string L’une des valeurs suivantes qui spécifie l’objectif de la campagne :
  • DriveInstall
  • DriveReengagement
  • DriveInAppPurchase
 Non DriveInstall Oui
lignes tableau Un ou plusieurs objets qui identifient les lignes de distribution associées à la campagne publicitaire. Chaque objet de ce champ se compose d’un champ id et nom qui spécifie l’ID et le nom de la ligne de livraison. Non Non
createdDate string Date et heure de création de la campagne de publicité, au format ISO 8601. Oui Non