Delivery API Overview

In order to rank Content, your API server needs to call Promoted's Delivery API. Similar integrations works for initial logging to Promoted, running experiments, and fully launching Promoted's rankings.

Integration

The Promoted server-side SDK is called in your API server after retrieval and any internal ranking steps. Learn more about why Promoted has a server-side SDK.

The main inputs to the SDK are a list of Requests and a list of Insertion candidates.

• Request: A list of content. This includes search, feed, and related items. Promoted uses a Protobuf schema.
• Insertion: A content candidate when processing a Request. Promoted starts with many potential Request Insertions, generated by the client's retrieval, and narrows down to a subset of Response Insertions to return to the UI. Note that Insertions are different from Impressions; an Impression is an Insertion that is viewed by the user.

Promoted has Delivery client libraries in multiple languages and can add support for additional languages if needed. Detailed integration instructions are found in each SDK doc on GitHub.

Here is an example code block for Typescript.

static async promotedDeliver(req: any, products: Product[], res: Response) {
  const responsePromise = promotedClient.deliver({
    // onlyLog: true - if you want to only log to Promoted.
    request: {
      userInfo: {
        anonUserId: req.anonUserId,
      },
      useCase: 'SEARCH', // Supports other enum values like 'FEED' and 'DISCOVER'.
      device: {
        browser: {
          userAgent: "Mozilla/5.0 ..."
        }
      },
      searchQuery: 'cars'
      properties: {
        struct: {
          // TODO - Add user, request and context features.
          // TODO - Add request filters.  The properties are used to generate a paging key that is used for caching.
        }
      },
      insertion: products.map((product, retrievalRank) => ({
        contentId: product.id,
        retrievalRank,
        properties: {
          struct: {
            // TODO - add user-item features here.
            // Example: "numReviews": product.numReviews,
          },
        },
      })),
    },
  });
  // Construct the map while the RPC is happening.
  const productIdToProduct = products.reduce<Record<string,Product>>((map, product) => {
      map[product.id] = product;
      return map;
  }, {});
  const clientResponse = await responsePromise;
  const responseProducts = toContents<Product>(clientResponse.insertion, productIdToProduct);

  // Change the response Product list to use the values in the returned Insertions.
  sendSuccessToClient(res, { products: responseProducts) });
  // Do not block.  Log asynchronously.
  clientResponse.log().catch(handleError);
}

Passing data on request

Promoted uses various data to optimize rankings. Most data is sent asynchronously through the Content API, but some data is only available in real-time on the Delivery API call. This is where interaction features (combinations of content, user, and context) should be passed in.

Example fields on the request:

• Your own retrieval scores
• Dynamic price
• Dynamic UI badges

See the Metrics and Content sections for explanations on how to send data to Promoted.

📘

Sending search queries to Promoted improves the ranking. Even if your system lacks a dedicated query field, you should still form a relelvant query and send it to Promoted.

For example, location-based marketplaces (e.g., hotel booking) may not have a search query bar. Promoted advises these marketplaces to send the user's desired location as the search query, in addition to the other fields. Please contact Promoted for more details on how to form your search query.

Data that impacts ranking should be passed in using one of two options:

1. The Delivery API call. This is used for real-time data that must be sent synchronously.
2. The Content API (asynchronous). This can be used for passing stable item or user data.

While it is possible to pass stable item or user features on the Delivery API call, it is advisable to use the Content API for these features to improve speed and prepare for scaling.

Selected UserInfo fields

Promoted provides a UserInfo field for internal usage and testing.