教學課程:內容相關決策制訂的文章個人化Tutorial: Article personalization for contextual decision making

本教學課程著重於網站首頁上精選文章的個人化。This tutorial focuses on personalizing the selection of articles on the front page of a website. 例如,自訂決策服務會影響首頁上多個 清單。The Custom Decision Service affects multiple lists of articles on the front page, for instance. 假設該頁面是僅提供政治和體育消息的新聞網站,Perhaps the page is a news website that covers only politics and sports. 網站上會顯示三種等級的文章清單:政治、體育和最新消息。It would show three ranked lists of articles: politics, sports, and recent.

應用程式和動作集合Applications and action sets

以下是如何讓您的情況符合架構。Here's how to fit your scenario into the framework. 假設有三個應用程式,每個均會列出經過最佳化的清單:app-politics、app-sports、app-recent。Let's imagine three applications, one for each list that is being optimized: app-politics, app-sports, and app-recent. 若要為每個應用程式指定候選文章,有兩個動作集合:一個用於政治,另一個用於體育。To specify the candidate articles for each application, there are two action sets: one for politics and one for sports. app-recent 的動作集合會自動成為其他兩組的集合聯集。The action set for app-recent comes automatically as a union of the other two sets.

提示

自訂決策服務的應用程式之間可共用動作集合。Action sets can be shared across applications in Custom Decision Service.

準備動作集合摘要Prepare action set feeds

自訂決策服務會透過客戶提供的 RSS 或 Atom 摘要取用動作集合。Custom Decision Service consumes action sets via RSS or Atom feeds provided by the customer. 您提供兩個摘要:一個適用於政治,另一個適用於體育。You provide two feeds: one for politics and one for sports. 假設皆由 http://www.domain.com/feeds/<feed-name> 提供。Suppose they are served from http://www.domain.com/feeds/<feed-name>.

每個摘要會提供一份文章清單。Each feed provides a list of articles. 在 RSS 中,每個摘要皆由 <item> 元素指定,如下所示:In RSS, each one is specified by an <item> element, as follows:

<rss version="2.0"><channel>
   <item>
      <title><![CDATA[article title]]></title>
      <link>"article url"</link>
      <pubDate>publication date</pubDate>
    </item>
</channel></rss>

文章的順序很重要。The order of articles matters. 該元素可指定預設順位,盡可能猜測文章最佳的排序方式。It specifies the default ranking, which is your best guess for how the articles should be ordered. 接著,會在儀表板上使用預設順位來比較效果。The default ranking is then used for performance comparison on the dashboard.

如需摘要格式的更多資訊,請參閱 API 參考For more information on the feed format, see the API reference.

註冊新的應用程式Register a new app

  1. 使用您的 Microsoft 帳戶登入。Sign in with your Microsoft account. 在功能區中,按一下 [我的入口網站] 。On the ribbon, click My Portal.

  2. 若要註冊新的應用程式,請按一下 [新應用程式] 按鈕。To register a new application, click the New App button.

    自訂決策服務入口網站

  3. 應用程式識別碼文字方塊中輸入應用程式的唯一名稱。Enter a unique name for your application in the App ID text box. 如果此名稱已由另一位客戶使用中,系統會要求您選取其他應用程式識別碼。If this name is already in use by another customer, the system asks you to pick a different app ID. 選取 [進階] 核取方塊,然後為您的 Azure 儲存體帳戶輸入 [連接字串]Select the Advanced check box, and enter the connection string for your Azure storage account. 通常,您會為所有應用程式使用相同的儲存體帳戶。Normally, you use the same storage account for all your applications.

    新應用程式對話方塊

    在上述情況下註冊所有三個應用程式後,它們會列出:After you register all three applications in the above scenario, they are listed:

    應用程式清單

    您可以按一下 [應用程式] 按鈕以返回此清單。You can come back to this list by clicking the Apps button.

  4. 在 [新應用程式] 對話方塊中,指定動作摘要。In the New App dialog box, specify an action feed. 您也可以按一下 [摘要] 按鈕,然後按一下 [新摘要] 按鈕,以指定動作摘要。Action feeds can also be specified by clicking the Feeds button and then by clicking the New Feed button. 輸入新摘要的 [名稱] ,然後輸入提供該摘要的 [URL] ,並輸入 [重新整理時間] 。Enter a Name for the new feed, enter the URL from which it is served, and enter the Refresh Time. 重新整理時間可指定自訂決策服務應該重新整理摘要的頻率。The refresh time specifies how frequently Custom Decision Service should refresh the feed.

    新摘要對話方塊

    無論是在何處指定動作摘要,這些動作摘要皆可供任何應用程式使用。Action feeds can be used by any app, regardless of where they're specified. 在案例中指定兩個動作摘要後,即會列出:After you specify both action feeds in a scenario, they are listed:

    摘要清單

    您可以按一下 [摘要] 按鈕以返回此清單。You can come back to this list by clicking the Feeds button.

使用 APIUse the APIs

自訂決策服務會透排名 API 來排列文章順位。The Custom Decision Service ranks articles via the Ranking API. 若要使用此 API,請將下列程式碼插入首頁的 HTML 開頭:To use this API, insert the following code into the HTML head of the front page:

<!-- Define the "callback function" to render UI -->
<script> function callback(data) { … } </script>

<!--  call Ranking API after callback() is defined, separately for each app -->
<script src="https://ds.microsoft.com/api/v2/app-politics/rank/feed-politics" async></script>
<script src="https://ds.microsoft.com/api/v2/app-sports/rank/feed-sports" async></script>
<script src="https://ds.microsoft.com/api/v2/app-recent/rank/feed-politics/feed-sports" async></script>
<!-- NB: action feeds for 'app-recent' are listed one after another. -->

來自排名 API 的 HTTP 回應會是 JSONP 格式字串。The HTTP response from the Ranking API is a JSONP-formatted string. 對於 app-politics,例如,字串如下所示:For app-politics, for example, the string looks like:

callback({
   "ranking":[{"id":"url1"}, {"id":"url2"}, {"id":"url3"}],
   "eventId":"<opaque event string>",
   "appId":"app-politics",
   "actionSets":[{"id":"feed-politics","lastRefresh":"date"}] });

瀏覽器會接著執行此字串作為 callback() 函式的呼叫。The browser then executes this string as a call to the callback() function. callback() 函式中的 data 引數包含應用程式識別碼,以及要呈現的 URL 順位。The data argument in the callback() function contains the app ID and the ranking of URLs to be rendered. 特別是,callback() 應會使用 data.appId 區別這三個應用程式。In particular, callback() should use data.appId to distinguish between the three applications. 自訂決策服務會在內部使用 eventId 來比對提供的順位與對應的點選 (若有)。eventId is used internally by Custom Decision Service to match the provided ranking with the corresponding click, if any.

提示

callback() 可能會藉由使用 lastRefresh 欄位檢查每個動作摘要的時效性。callback() might check each action feed for freshness by using the lastRefresh field. 如果提供的摘要不夠新,則 callback() 可能會忽略提供的順位,直接呼叫此摘要,並使用由摘要提供的預設順位。If a given feed is not sufficiently fresh, callback() might ignore the provided ranking, call this feed directly, and use the default ranking served by the feed.

如需更多規格和排名 API 提供之其他選項的相關資訊,請參閱 API 參考For more information on specifications and additional options provided by the Ranking API, see the API reference.

呼叫獎勵 API,可傳回使用者的最優先的文章選擇。The top article choices from the user are returned by calling the Reward API. 收到優先文章選擇之後,會在首頁叫用下列程式碼:When a top article choice is received, the following code should be invoked on the front page:

$.ajax({
    type: "POST",
    url: '//ds.microsoft.com/api/v2/<appId>/reward/<eventId>',
    contentType: "application/json" })

在點擊處理程式碼中使用 appIdeventId 需要特別小心。Using appId and eventId in the click-handling code requires some care. 例如,您可以實作 callback() 函數,如下所示:For example, you can implement the callback() function as follows:

function callback(data) {
    $.map(data.ranking, function (element) {
        //custom rendering function given content info
        render({appId:data.appId,
                article:element,
                onClick: element.id != data.rewardAction ? null :
                   function() {
                       $.ajax({
                       type: "POST",
                       url: '//ds.microsoft.com/api/v2/' + data.appId + '/reward/' + data.eventId,
                       contentType: "application/json" })}
                });
}}

在此範例中,請實作 render() 函數,以針對指定的應用程式轉譯指定的文章。In this example, implement the render() function to render a given article for a given application. 此函數會輸入應用程式識別碼和文章 (使用排名 API 的格式)。This function inputs the app ID and the article (in the format from the Ranking API). onClick 參數是應從 render() 呼叫處理點擊的函數。The onClick parameter is the function that should be called from render() to handle a click. 它會檢查該點擊是否位於最上方的位置。It checks whether the click is on the top slot. 然後使用適當的應用程式識別碼和事件識別碼呼叫獎勵 API。Then it calls the Reward API with the appropriate app ID and event ID.

後續步驟Next steps

  • 請參閱 API 參考以深入了解提供的功能。Consult the API reference to learn more about the provided functionality.