promoted-ruby-client

Ruby client designed for calling Promoted's Delivery and Metrics API.

More information at http://www.promoted.ai

Installation

gem 'promoted-ruby-client'

Local Development

1. Clone or fork the repo on your local machine
2. cd promoted-ruby-client
3. bundle
4. To test interactively: irb -Ilib -rpromoted/ruby/client

Dependencies

Faraday

HTTP client for calling Promoted.

Net::HTTP::Persistent

Faraday binding (provides connection pool support)

Concurrent Ruby

Provides a thread pool for making shadow traffic requests to Delivery API in the background on a subset of calls to deliver

Creating a Client

client=Promoted::Ruby::Client::PromotedClient.new

This client will suffice for building log requests. To send actually send traffing to the API, some configuration is required.

client=Promoted::Ruby::Client::PromotedClient.new({:metrics_endpoint=>"https://<get this from Promoted>",:delivery_endpoint=>"https://<get this from Promoted>",:metrics_api_key=>"<get this from Promoted>",:delivery_api_key=>"<get this from Promoted>"})

Client Configuration Parameters

Name	Type	Description
:delivery_endpoint	String	POST URL for the Promoted Delivery API (get this from Promoted)
:metrics_endpoint	String	POST URL for the Promoted Metrics API (get this from Promoted)
:metrics_api_key	String	Used as the x-api-key header on Metrics API requests to Promoted (get this value from Promoted)
:delivery_api_key	String	Used as the x-api-key header on Delivery API requests to Promoted (get this value from Promoted)
:delivery_timeout_millis	Number	Timeout on the Delivery API call. Defaults to 3000.
:metrics_timeout_millis	Number	Timeout on the Metrics API call. Defaults to 3000.
:perform_checks	Boolean	Whether or not to perform detailed input validation, defaults to true but may be disabled for performance
:logger	Ruby Logger-compatible logger	Defaults to nil (no logging). Example: Logger.new(STDERR, :progname => 'promotedai')
:shadow_traffic_delivery_percent	Number between 0 and 1	% of deliver traffic that gets directed to Delivery API as "shadow traffic". Defaults to 0 (no shadow traffic).
:send_shadow_traffic_for_control	Boolean	If true, the deliver method will send shadow traffic for users in the CONTROL arm of an experiment. Defaults to true.
:default_request_headers	Hash	Additional headers to send on the request beyond x-api-key. Defaults to {}
:default_only_log	Boolean	If true, the deliver method will not direct traffic to Delivery API but rather return a request suitable for logging. Defaults to false.
:should_apply_treatment_func	Proc	Called during delivery, accepts an experiment and returns a Boolean indicating whether the request should be considered part of the control group (false) or in the experiment (true). If nil, the default behavior of checking the experiement :arm is applied.
:warmup	Boolean	If true, the client will prime the Net::HTTP::Persistent connection pool on construction; this can make the first few calls to Promoted complete faster. Defaults to false.
:max_request_insertions	Number	Maximum number of request insertions that will be passed to Delivery API on a single request (any more will be truncated by the SDK). Defaults to 1000.

Data Types

UserInfo

Basic information about the request user.

Field Name	Type	Optional?	Description
:user_id	String	Yes	The platform user id, cleared from Promoted logs.
:anon_user_id	String	Yes	A different user id (presumably a UUID) disconnected from the platform user id, good for working with unauthenticated users or implementing right-to-be-forgotten.
:is_internal_user	Boolean	Yes	If this user is a test user or not, defaults to false.
:ignore_usage	Boolean	Yes	If you want to ignore usage from this user, defaults to false.

---

CohortMembership

Useful fields for experimentation during the delivery phase.

Field Name	Type	Optional?	Description
:user_info	UserInfo	Yes	The user info structure.
:arm	String	Yes	'CONTROL' or one of the TREATMENT values (see constants.rb).

---

Properties

Properties bag. Has the structure:

:struct=>{:product=>{"id": "product3","title": "Product 3","url": "www.mymarket.com/p/3"# other key-value pairs...}}

---

Insertion

Content being served at a certain position.

Field Name	Type	Optional?	Description
:user_info	UserInfo	Yes	The user info structure.
:insertion_id	String	Yes	Generated by the SDK (do not set)
:request_id	String	Yes	Generated by the SDK when needed (do not set)
:content_id	String	No	Identifier for the content to be shown, must be set.
:retrieval_rank	Number	Yes	Optional original ranking of this content item.
:retrieval_score	Number	Yes	Optional original quality score of this content item.
:properties	Properties	Yes	Any additional custom properties to associate. For v1 integrations, it is fine not to fill in all the properties.

---

Size

User's screen dimensions.

Field Name	Type	Optional?	Description
:width	Integer	No	Screen width
:height	Integer	No	Screen height

---

Screen

State of the screen including scaling.

Field Name	Type	Optional?	Description
:size	Size	Yes	Screen size
:scale	Float	Yes	Current screen scaling factor

---

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

Field Name	Type	Optional?	Description
:is_mobile	Boolean	Yes	Mobile flag
:brand	Array of ClientBrandHint	Yes
:architecture	String	Yes
:model	String	Yes
:platform	String	Yes
:platform_version	String	Yes
:ua_full_version	String	Yes

---

ClientBrandHint

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

Field Name	Type	Optional?	Description
:brand	String	Yes	Mobile flag
:version	String	Yes

---

Location

Information about the user's location.

Field Name	Type	Optional?	Description
:latitude	Float	No	Location latitude
:longitude	Float	No	Location longitude
:accuracy_in_meters	Integer	Yes	Location accuracy if available

---

Browser

Information about the user's browser.

Field Name	Type	Optional?	Description
:user_agent	String	Yes	Browser user agent string
:viewport_size	Size	Yes	Size of the browser viewport
:client_hints	ClientHints	Yes	HTTP client hints structure
referrer	String	Yes	Request referrer

---

Device

Information about the user's device.

Field Name	Type	Optional?	Description
:device_type	one of (UNKNOWN_DEVICE_TYPE, DESKTOP, MOBILE, TABLET)	Yes	Type of device
:brand	String	Yes	"Apple, "google", Samsung", etc.
:manufacturer	String	Yes	"Apple", "HTC", Motorola", "HUAWEI", etc.
:identifier	String	Yes	Android: android.os.Build.MODEL; iOS: iPhoneXX,YY, etc.
:screen	Screen	Yes	Screen dimensions
:ip_address	String	Yes	Originating IP address
:location	Location	Yes	Location information
:browser	Browser	Yes	Browser information

---

Paging

Paging parameters.

DeliveryRequest.retrieval_insertion_offset also impacts paging. That field indicate the offset of the retrieved insertions that are passed into Request.insertion. See detailed documentation on paging and retrieval_insertion_offset.

Field Name	Type	Optional?	Description
:offset	Integer	Yes	The 0-based, starting index for the response page. This should be the global position.
:size	Integer	Yes	The number of items to return in a response page.

---

Request

A request for content insertions.

Field Name	Type	Optional?	Description
:user_info	UserInfo	Yes	The user info structure.
:request_id	String	Yes	Generated by the SDK when needed (do not set)
:use_case	String	Yes	One of the use case values, i.e. 'FEED' (see constants.rb).
:properties	Properties	Yes	Any additional custom properties to associate.
:paging	Paging	Yes	Paging parameters
:device	Device	Yes	Device information (as available)
:disable_personalization	Boolean	Yes	If true, disables personalized inputs into Delivery algorithm.

---

DeliveryRequest

Input to deliver

Field Name	Type	Optional?	Description
:experiment	CohortMembership	Yes	A cohort to evaluation in experimentation.
:request	Request	No	The underlying request for content.
:only_log	Boolean	Yes	Defaults to false. Set to true to override whether Delivery API is called for this request.
:retrieval_insertion_offset	Integer	Yes	The index of the retrieved insertions set on Request.insertion list. If just sending the top-N from your retrieval, this is 0. If this is the next batch (e.g. 500 to 999), then the value is 500. This can be used to send multiple groups of retrieved insertions. This interacts with the Paging fields. More detailed documentation on paging.

---

LogRequest

A log object that is sent as a RPC request to Promoted's Metrics API log endpoint. This is outputted from the deliver SDK call. Callers need to either input it into the send_log_request method or send it to the Metrics API directly. Clients should avoid manipulating this object directly.

ClientResponse

Output of deliver, includes the insertions as well as a suitable LogRequest for forwarding to Metrics API.

Field Name	Type	Optional?	Description
:insertion	[] of Insertion	No	The paged insertions, which are from Delivery API (when deliver was called, i.e. we weren't either only-log or part of an experiment) or the input insertions (when the other conditions don't hold).
:log_request	LogRequest	Yes	A message suitable for logging to Metrics API via send_log_request. If the call to deliver was made (i.e. the request was not part of the CONTROL arm of an experiment or marked to only log), :log_request will not be set, as you can assume logging was performed on the server-side by Promoted.
:client_request_id	String	Yes	Client-generated request id sent to Delivery API and may be useful for logging and debugging.
:execution_server	one of 'API' or 'SDK'	Yes	Indicates if response insertions on a delivery request came from the API or the SDK.

---

PromotedClient

Method	Input	Output	Description
send_log_request	LogRequest	n/a	Forwards a LogRequest to Promoted using an HTTP client.
deliver	DeliveryRequest	ClientResponse	Depending on flags, either (1) makes a request (subject to experimentation) to Delivery API for insertions, which are then returned along with a LogRequest or (2) implements SDK-side paging and prepares log records that can be logged to Promoted using send_log_request or by using this structure to make the call yourself. Optionally, based on client configuration may send a random subset of requests to Delivery API as shadow traffic for integration purposes.
close	n/a	n/a	Closes down the client at shutdown, currently this is just to drain the thread pool that handles shadow traffic.

---

Metrics API

Expected flow for Metrics logging

# Retrieve a list of content (i.e. products)# products = fetch_my_marketplace_products()products=[{id: "123",type: "SHOE",name: "Blue shoe",total_sales: 1000},{id: "124",type: "SHIRT",name: "Green shirt",total_sales: 800},{id: "125",type: "DRESS",name: "Red dress",total_sales: 1200}]# Transform them into an [] of Insertions.insertions=products.map{ |product| {:content_id=>product[:id],:properties=>{:struct=>{:type=>product[:type],:name=>product[:name]# etc}}}}# Form a MetricsRequestmetrics_request={:request=>{:user_info=>{:user_id=>"912",:anon_user_id=>"912191"},:use_case=>"FEED",:paging=>{:offset=>0,:size=>5},:properties=>{:struct=>{:active=>true}},:insertion=>insertions},:only_log=>true,}# Create a clientclient=Promoted::Ruby::Client::PromotedClient.new# Build a log requestclient_response=client.deliver(metrics_request)# Log (assuming you have configured your client with a :metrics_endpoint)client.send_log_request(client_response[:log_request])ifclient_response[:log_request]

Delivery API

Expected flow for Delivery

# (continuing from the above example for Metrics)# Form a DeliveryRequestdelivery_request={:request=>{:user_info=>{:user_id=>"912",:anon_user_id=>"912191"},:use_case=>"FEED",:paging=>{:offset=>0,:size=>5},:properties=>{:struct=>{:active=>true}},:insertion=>insertions,},:only_log=>false}# Request insertions from Delivery APIclient_response=client.deliver(delivery_request)# Use the resulting insertionsclient_response[:insertion]# Log if a log request was provided (if not, deliver was called successfully# and Promoted logged on the server-side).)client.send_log_request(client_response[:log_request])ifclient_response[:log_request]

TODO Experimentation example