Create a custom app promotion campaign

In addition to creating an ad campaign for your app that will run in Windows apps, you can also promote your app using other channels. For example, you can promote your app using a third-party app marketing provider, or you might post links to your app on social media sites. These activities are called custom campaigns.

If you run custom campaigns for your app, you can track the relative performance of each campaign by creating a different Windows Store app URL for each custom campaign, where each URL contains a different campaign ID. When a customer running Windows 10 clicks a URL that contains a campaign ID, Microsoft associates the click with the corresponding custom campaign and makes this data available to you.

There are two main types of data associated with custom campaigns: page views for your app and conversions. A conversion is an app acquisition that results from a customer clicking on the Windows Store page for your app from a URL that is promoted via a custom campaign. For more details about conversions, see Understanding how app acquisitions qualify as conversions in this topic.

You can retrieve custom campaign performance data for your app in the following ways:

  • You can view data about page views and conversions for your app or add-on from the Channels and conversions report in the Dev Center dashboard.
  • If your app is a Universal Windows Platform (UWP) app, it can use APIs in the Windows SDK to programmatically retrieve the custom campaign ID that resulted in a conversion.

Important  This data will only be tracked for customers running Windows 10. Customers using other operating systems can still follow the link to your app's listing, but data about those customers' activities will not be included.

Example custom campaign scenario

Consider a game developer who has finished building a new game and would like to promote it to players of her existing games. She posts the announcement of the new game release on her Facebook page, including a link to the Windows Store page for the game. Many of her players also follow her on Twitter, so she also tweets the announcement with the link to the Windows Store page for the game.

To track the success of each of these promotion channels, the developer creates two variants of the URL for the Windows Store page for the game:

  • The URL she will post to her Facebook page includes the custom campaign ID my-facebook-campaign.
  • The URL she will post to Twitter includes the custom campaign ID my-twitter-campaign.

As her Facebook and Twitter followers click on the URLs, Microsoft tracks each click and associates it with the corresponding custom campaign. Subsequent qualifying acquisitions of the game and any add-on purchases are associated with the custom campaign and reported as conversions.

Understanding how app acquisitions qualify as conversions

A conversion is an app acquisition that results from a customer clicking on the Windows Store page for your app from a URL that is promoted via a custom campaign. There are different scenarios for qualifying as a conversion for the Channels and conversions report on the Dev Center dashboard and for qualifying as a conversion for programmatically retrieving the campaign ID.

Qualifying conversions for the dashboard report

The following scenarios qualify as a conversion for the Channels and conversions report:

  • A customer with or without a recognized Microsoft account clicks an app URL that contains a custom campaign ID and is redirected to the Windows Store page for the app. The same customer acquires the app within 24 hours after they first clicked the Windows Store URL with the custom campaign ID.

  • If the customer acquires the app on a different computer or device than the one on which they clicked the Windows Store URL with the custom campaign ID, the conversion will only be counted if the customer has a Microsoft account.

Note  For app acquisitions that are counted as conversions for a custom campaign, any add-on purchases in that app are also counted as conversions for the same custom campaign.

Qualifying conversions for programmatically retrieving the campaign ID

To qualify as a conversion when programmatically retrieving the campaign ID associated with the app, the following conditions must be met:

  • On a device running Windows 10, version 1607, or later: A customer with or without a recognized Microsoft account clicks an app URL that contains a custom campaign ID and is redirected to the Windows Store page for the app. The customer acquires the app during the same Windows Store page view after they click the URL.

  • On a device running Windows 10, version 1511, or earlier: A customer with a recognized Microsoft account clicks an app URL that contains a custom campaign ID and is redirected to the Windows Store page for the app. The customer acquires the app during the same Windows Store page view after they click the URL. On these versions of Windows 10, the user must have a recognized Microsoft account in order for the acquisition to qualify as a conversion when programmatically retrieving the campaign ID.

Note  If the customer leaves the page and then returns to the page (either on the same computer or device or on a different computer or device if they have a Microsoft account) within 24 hours and acquires the app, this will qualify as a conversion on the Channels and conversions report. However, this will not qualify as a conversion if you programmatically retrieve the campaign ID.

Embed a custom campaign ID to your app's Windows Store page URL

To create a Windows Store page URL for your app with a custom campaign ID:

  1. Create an ID string for your custom campaign. This string can contain up to 100 characters, although we recommend that you define short campaign IDs that are easily identifiable.

    Note  The campaign ID string may be visible to other developers within a Channels and conversions report. This can occur when a customer clicks on your campaign ID to enter the Store, but ends up purchasing another developer’s app within the same session. Even though your campaign ID name may be visible to another developer in this case, that developer will only see how many conversions of their own app resulted from an initial click on your campaign ID. They will not see any data about how many users purchased your app from clicking on your campaign ID.

  2. Get the Windows Store page URL for your app in HTML or protocol format.

    • Use the HTTP format if you want customers to navigate to your app's Windows Store page in a browser (this URL will also launch the Windows Store app to your app's listing, if the Windows Store app is installed). This URL has the format https://www.microsoft.com/store/apps/*your app name*/*your app ID*. For example, the HTTP URL for Skype is https://www.microsoft.com/store/apps/skype/9wzdncrfj364. The HTML format URL is available on the App Identity page in the Dev Center dashboard. Note that HTTP format URLs can be used to navigate to the Windows Store in a browser on computers and tablets running Windows 7 and later, and phones running Windows Phone 8 and later.

    • Use the protocol format if you are promoting your app from other Windows apps that are running on a device or computer with the Windows Store app installed, and you want customers to open to your app's page in the Windows Store app. This URL has the format ms-windows-store://pdp/?PRODUCTID=*your app id*. For example, the protocol URL for Skype is ms-windows-store://pdp/?PRODUCTID=9wzdncrfj364.

  3. Append the following string to the end of the URL for your app:

    • For an HTTP format URL, append ?cid=*my custom campaign ID*. For example, if Skype introduces a campaign ID with the value custom_campaign, the new HTTP URL including the campaign ID would be: https://www.microsoft.com/store/apps/skype/9wzdncrfj364?cid=custom\_campaign.

    • For a protocol format URL, append &cid=*my custom campaign ID*. For example, if Skype introduces a campaign ID with the value custom_campaign, the new protocol URL including the campaign ID would be: ms-windows-store://pdp/?PRODUCTID=9wzdncrfj364&cid=custom\_campaign.

Programmatically retrieve the custom campaign ID for an app

If your app is a UWP app, you can programmatically retrieve the custom campaign ID associated with your app by using APIs in the Windows SDK. These APIs make many analytics and monetization scenarios possible. For example, you can find out if the current user acquired your app after discovering it through your Facebook campaign, and then customize the app experience accordingly. Alternatively, if you are using a third-party app marketing provider, you can send data back to the provider.

These APIs will return a campaign ID string only if the customer clicks your URL with the embedded campaign ID, is redirected to the Windows Store page for your app, and then acquires your app without leaving this page. If the user leaves the page and then later returns and acquires the app, this will not qualify as a conversion when using these APIs.

There are different APIs for you to use depending on the version of Windows 10 that your app targets:

  • Windows 10, version 1607, or later: Use the StoreContext class in the Windows.Services.Store namespace. When using this API, you can retrieve custom campaign IDs for any qualified acquisitions, whether or not the user has a recognized Microsoft account.
  • Windows 10, version 1511, or earlier: Use the CurrentApp class in the Windows.ApplicationModel.Store namespace. When using this API, you can only retrieve custom campaign IDs for qualified acquisitions where the user has a recognized Microsoft account.

Note  Although the Windows.ApplicationModel.Store namespace is available in all versions of Windows 10, we recommend that you use the APIs in the Windows.Services.Store namespace if your app targets Windows 10, version 1607, or later. For more information about the differences between these namespaces, see In-app purchases and trials. The following code example shows how to structure your code to use both APIs in the same project.

Code example

The following code example shows how to retrieve the custom campaign ID. This example uses both sets of APIs in the Windows.Services.Store and Windows.ApplicationModel.Store namespaces by using version adaptive code. By following this process, your code can run on any version of Windows 10. To use this code, the target OS version of your project must be Windows 10 Anniversary Edition (10.0; Build 14394) or later, although the minimum OS vesion can be an earlier version.

// This example assumes the code file has using statements for
// System.Linq, System.Threading.Tasks, Windows.Data.Json,
// and Windows.Services.Store.
public async Task<string> GetCampaignId()
{
    // Use APIs in the Windows.Services.Store namespace if they are available
    // (the app is running on a device with Windows 10, version 1607, or later).
    if (Windows.Foundation.Metadata.ApiInformation.IsTypePresent(
         "Windows.Services.Store.StoreContext"))
    {
        StoreContext context = StoreContext.GetDefault();

        // Try to get the campaign ID for users with a recognized Microsoft account.
        StoreProductResult result = await context.GetStoreProductForCurrentAppAsync();
        if (result.Product != null)
        {
            StoreSku sku = result.Product.Skus.FirstOrDefault(s => s.IsInUserCollection);

            if (sku != null)
            {
                return sku.CollectionData.CampaignId;
            }
        }

        // Try to get the campaign ID from the license data for users without a
        // recognized Microsoft account.
        StoreAppLicense license = await context.GetAppLicenseAsync();
        JsonObject json = JsonObject.Parse(license.ExtendedJsonData);
        if (json.ContainsKey("customPolicyField1"))
        {
            return json["customPolicyField1"].GetString();
        }

        // No campaign ID was found.
        return String.Empty;
    }
    // Fall back to using APIs in the Windows.ApplicationModel.Store namespace instead
    // (the app is running on a device with Windows 10, version 1577, or earlier).
    else
    {
#if DEBUG
        return await Windows.ApplicationModel.Store.CurrentAppSimulator.GetAppPurchaseCampaignIdAsync();
#else
        return await Windows.ApplicationModel.Store.CurrentApp.GetAppPurchaseCampaignIdAsync() ;
#endif
    }
}

This code does the following:

  1. First, it checks to see if the StoreContext class in the Windows.Services.Store namespace is available on the current device (this means the device is running Windows 10, version 1607, or later). If so, the code proceeds to use this class.

  2. Next, it attempts to get the custom campaign ID for the case where the current user has a recognized Microsoft account. To do this, the code gets a StoreSku object that represents the current app SKU, and then it accesses the CampaignId property to retrieve the campaign ID, if one is available.

  3. The code then attempts to retrieve the campaign ID for the case where the current user does not have a recognized Microsoft account. In this case, the campaign ID is embedded in the app license. The code retrieves the license by using the GetAppLicenseAsync method and then parses the JSON contents of the license for the value of a key named customPolicyField1. This value contains the campaign ID.

  4. If the StoreContext class in the Windows.Services.Store namespace is not available, the code then falls back to using the GetAppPurchaseCampaignIdAsync method in the Windows.ApplicationModel.Store namepsace to retrieve the custom campaign ID (this namespace is available in all versions of Windows 10, including version 1511 and earlier). Note that when using this method, you can only retrieve custom campaign IDs for qualified acquisitions where the user has a recognized Microsoft account.

    Note  The Windows.ApplicationModel.Store namespace includes CurrentAppSimulator, a special class that simulates Store operations for testing your code before you submit your app to the Store. This class retrieves data from a local file named Windows.StoreProxy.xml file. The previous code example shows how to include use both CurrentApp and CurrentAppSimulator in debug and non-debug code in your project. To test this code in a debug environment, add an AppPurchaseCampaignId element to the WindowsStoreProxy.xml file on your development computer, as shown in the following example. When you run the app, the GetAppPurchaseCampaignIdAsync method will always return this value.

    <CurrentApp>
       ...
       <AppPurchaseCampaignId>your custom campaign ID</AppPurchaseCampaignId>
    </CurrentApp>
    

    Note  The Windows.Services.Store namespace does not provide a class that you can use to simulate license info during testing. Instead, you must publish an app to the Store and download that app to your development device to use its license for testing. For more information, see In-app purchases and trials.

Test your custom campaign

Before you promote a custom campaign URL, we recommend that you test your custom campaign by doing the following:

  1. Sign in to your Microsoft Account on the computer or device you are using for testing.
  2. Click your custom campaign URL. Make sure the Windows Store loads your app page correctly, and then close the Windows Store app or the browser page.
  3. Click the URL several more times, closing the Windows Store app or the browser page after each visit to your app's page. During one of the visits to your app's page, acquire your app to generate a conversion. Count the total number of times you clicked the URL.
  4. Confirm whether the expected page views and conversions appear in the Channels and conversions report, and test your app code to confirm whether it can successfully retrieve the campaign ID.