Promoted.DeliveryClient 0.2.0

promoted-dotnet-delivery-client

.NET (targeting netstandard2.0) client SDK for the Promoted.ai Delivery API

Features

• Demonstrates and implements the recommended practices and data types for calling Promoted.ai's Delivery API.
• Client-side position assignment and paging when not using results from Delivery API, for example when logging only or as part of an experiment control.

Creating a DeliveryClient

The Promoted.Lib.DeliveryClient is currently intended to have one instance per pair (Delivery and Metrics) of endpoints. It is thread-safe, but is built on top of System.Net.Http.HttpClient so it implements IDisposable.

var logger = new Your.Namespace.LogAdapter();
var options = new Promoted.Lib.DeliveryClientOptions(); // Optional.
var client = new Promoted.Lib.DeliveryClient(
    deliveryEndpoint, deliveryApiKey, deliveryTimeoutMillis,
    metricsEndpoint, metricsApiKey, metricsTimeoutMillis,
    logger, options);
...
client.Dispose();

DeliveryClient Constructor Parameters

ILog interface

The methods which must be implemented for this interface are:

void Info(string message);
void Error(string message);

DeliveryClientOptions Properties

DeliveryClient Methods

DeliveryRequestOptions Properties

Calling the Delivery API

Let's say the previous code looks like this:

void async GetProducts(ProductRequest req):
    var products = ...; // Logic to get products from DB, apply filtering, etc.
    SendSuccessToClient(products)

We might modify to something like this:

void async GetProducts(ProductRequest req):
    var products = ...; // Logic to get products from DB, apply filtering, etc.

    List<Promoted.Delivery.Insertion> insertions = new List<Promoted.Delivery.Insertion>();
    // Keep a dictionary for reordering.
    Dictionary<string, Product> productMap = new Dictionary<string, Product>();
    foreach (Product product in products)
    {
        var insertion = new Promoted.Delivery.Insertion();
        insertion.ContentId = product.ProductId;
        insertions.Add(insertion);
        productMap.Add(product.ProductId, product);
    }

    var req = new Promoted.Delivery.Request();
    req.UserInfo = new Promoted.Common.UserInfo();
    req.UserInfo.UserId = "abc";
    req.Paging = new Delivery.Paging();
    req.Paging.Offset = 0;
    req.Paging.Size = 100;
    req.Insertion.AddRange(insertions);

    Promoted.Delivery.Response resp = await client.Deliver(req);

    List<Product> rankedProducts = new List<Product>();
    foreach (var insertion in resp.Insertion)
    {
        rankedProducts.Add(productMap[insertion.ContentId]);
    }

    SendSuccessToClient(rankedProducts)

Note that await client.Deliver(req) can throw here.

Data Types

UserInfo

Basic information about the request user.

CohortMembership

Useful fields for experimentation during the delivery phase.

Properties

Properties bag. Has the JSON structure:

  "struct": {
    "product": {
      "id": "product3",
      "title": "Product 3",
      "url": "www.mymarket.com/p/3"
      // Other <key, value> pairs...
    }
  }

Promoted.Delivery.Insertion

Content being served at a certain position.

Promoted.Common.Size

User's screen dimensions.

Promoted.Common.Screen

State of the screen including scaling.

Promoted.Common.ClientHints

Alternative to user-agent strings. See https://raw.githubusercontent.com/snowplow/iglu-central/master/schemas/org.ietf/http_client_hints/jsonschema/1-0-0.

Promoted.Common.ClientBrandHint

See https://raw.githubusercontent.com/snowplow/iglu-central/master/schemas/org.ietf/http_client_hints/jsonschema/1-0-0.

Promoted.Common.Location

Information about the user's location.

Promoted.Common.Browser

Information about the user's browser.

Promoted.Common.Device

Information about the user's device.

Promoted.Common.Paging

Describes a page of insertions.

Promoted.Delivery.Request

A request for content insertions.

Promoted.Delivery.Response

Output of Deliver(). Includes the ranked insertions for you to display.

Pages of Request Insertions

Clients can send a subset of all request insertions to Promoted in Delivery API's Request.Insertion array. The RetrievalInsertionOffset option specifies the start index of the array Request.Insertion in the list of ALL request insertions.

Request.Paging.Offset should be set to the zero-based position in ALL request insertions (not the relative position in the Request.Insertion array).

Examples

• If there are 10 items and all 10 items are in Request.Insertion, then RetrievalInsertionOffset=0.
• If there are 10,000 items and the first 500 items are on Request.Insertion, then RetrievalInsertionOffset=0.
• If there are 10,000 items and we want to send items [500,1000) on Request.Insertion, then RetrievalInsertionOffset=500.
• If there are 10,000 items and we want to send the last page [9500,10000) on Request.Insertion, then RetrievalInsertionOffset=9500.

RetrievalInsertionOffset is required to be less than Paging.Offset or else a ValueArgumentExceptionError will result.

Additional details: https://docs.promoted.ai/docs/ranking-requests#how-to-send-more-insertions-than-the-top-few-hundred

Position

• Do not set the insertion Position field in client code. The SDK and Delivery API will set it when Deliver() is called.

Logging only

You can use Deliver() but enable the OnlyLogToMetrics option.