管理廣告行銷活動

  • 發行項

在 Microsoft Store 促銷 API 中使用這些方法，為您的應用程式建立、編輯和取得促銷廣告活動。 您使用此方法建立的每個行銷活動只能與一個應用程式建立關聯。

注意：您也可以使用合作夥伴中心建立和管理廣告活動，且可在合作夥伴中心存取以程式設計方式建立的廣告活動。 如需在合作夥伴中心管理廣告行銷活動的詳細資訊，請參閱為您的應用程式建立廣告行銷活動。

當您使用這些方法來建立或更新行銷活動時，通常也會呼叫下列一或多個方法來管理與行銷活動相關聯的廣告播送行、受眾設定檔和創意內容。 有關行銷活動、廣告播送行、受眾設定檔和創意內容之間的關係詳細資訊，請參閱使用 Microsoft Store 服務執行廣告行銷活動。

必要條件

若要使用這些方法，您必須先執行下列動作：

  • 如果您尚未這麼做，請完成 Microsoft Store 促銷 API 的所有必要條件。

    注意：先決條件之一為請務必在合作夥伴中心建立至少一個付費廣告行銷活動，並在合作夥伴中心新增至少一個廣告行銷活動的付款方式。 您使用此 API 建立的廣告行銷活動廣告播送行，會自動向合作夥伴中心的 [廣告行銷活動] 頁面上選擇的預設付款方式計費。

  • 取得 Azure AD 存取權杖，以用於這些方法的要求標頭中。 取得存取權杖之後，您在其到期之前有 60 分鐘的時間可以使用。 權杖到期之後，您可以取得新的權杖。

要求

這些方法具有下列 URI。

方法類型 要求 URI 描述
POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign 建立新的廣告行銷活動。
PUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} 編輯 campaignId 所指定的廣告行銷活動。
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} 取得 campaignId 所指定的廣告行銷活動。
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign 廣告行銷活動的查詢。 如需支援的查詢參數，請參閱參數一節。
標題 類型 描述
授權 string 必要。 持有人<權杖>形式的Azure AD 存取權杖。
追蹤 ID GUID 選擇性。 追蹤呼叫流程的識別碼。

 

參數

查詢廣告行銷活動的 GET 方法支援下列選擇性查詢參數。

名稱 類型​​ 描述
skip int 要在查詢中忽略的列數。 使用此參數逐頁瀏覽資料集。 例如，fetch=10 和 skip=0 會擷取前 10 列資料，top=10 和 skip=10 會擷取接下來的 10 列資料，以此類推。
擷取 int 要求中要傳回的資料列數。
campaignSetSortColumn string 依指定的欄位排序回應本文中的行銷活動物件。 語法為 CampaignSetSortColumn=field，其中 field 參數可以是下列其中一個字串：

  • id
  • createdDateTime

預設為 createdDateTime。
isDescending 布林值 以遞減或遞增順序排序回應本文中的行銷活動物件。
storeProductId string 使用此值只傳回與具有指定 Store ID 應用程式相關聯的廣告行銷活動。 產品的 Store ID 範例為 9nblggh42cfd。
label string 使用此值只傳回在行銷活動 物件中包含指定 label 的廣告行銷活動。

要求本文

POST 和 PUT 方法需要一個 JSON 要求本文，其中包含行銷活動物件的必填欄位以及要設置或更改的任何其他欄位。

要求範例

下面的範例示範如何呼叫 POST 方法來建立廣告行銷活動。

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"
}

下面的範例示範如何呼叫 GET 方法來擷取特定的廣告行銷活動。

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

下列範例示範如何呼叫 GET 方法來查詢一組依建立日期排序的廣告行銷活動。

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>

回應

這些方法會根據您呼叫的方法，傳回一或多個行銷活動物件的 JSON 回應本文。 以下範例示範了特定行銷活動用於 GET 方法的回應正文。

{
    "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"
            }
        ]
    }
}

行銷活動物件

這些方法的要求和回應本文包含下欄欄位。 下表顯示哪些欄位是唯讀的 (表示無法在 PUT 方法中變更欄位)，以及 POST 方法的要求本文中需要哪些欄位。

欄位 類型 描述 唯讀 預設 POST 的必要項目
識別碼 整數 廣告行銷活動的識別碼。 是 No
NAME 字串 廣告行銷活動的名稱。 No Yes
configuredStatus string 下列其中一個值，指定開發人員所指定廣告行銷活動的狀態：
  • 使用中
  • 非使用中
 No 使用中 Yes
effectiveStatus string 下列其中一個值，可根據系統驗證指定廣告行銷活動的有效狀態：
  • 使用中
  • 非使用中
  • 正在處理
 是 No
effectiveStatusReasons 陣列 下列一或多個值，指定廣告行銷活動有效狀態的原因：
  • AdCreativesInactive
  • BillingFailed
  • AdLinesInactive
  • ValidationFailed
  • 失敗
 是 No
storeProductId string 與此廣告行銷活動相關聯的應用程式 Store 識別碼。 產品的 Store ID 範例為 9nblggh42cfd。 Yes Yes
標籤 陣列 代表行銷活動自訂標籤的一或多個字串。 這些標籤可用於搜尋和標記行銷活動。 No null No
type string 下列其中一個值，指定行銷活動類型：
  • 已支付
  • House
  • Community
 Yes Yes
objective string 下列其中一個值，指定行銷活動的目標：
  • DriveInstall
  • DriveReengagement
  • DriveInAppPurchase
 No DriveInstall Yes
線條 陣列 一或多個物件可用於識別與廣告行銷活動相關聯的廣告播送行。 此欄位中的每個物件都包含 id 和 name 欄位，來指定廣告播送行的識別碼和名稱。 No No
createdDate string 廣告行銷活動的建立日期和時間，格式為 ISO 8601。 是 No