Real Time Recommendations

This document describes how to obtain real-time recommendations from ShiftForward DMP by listening on a specific queue in an amqp-compliant broker.

Obtaining a queue

In order to start listening to real-time recommendations, a queue must first be created. In order to do so, perform an HTTP GET request to recommendations.adstax.customerdomain.com/recommendations/listen. The response should be a json similar to the following:

{
  "host": "mq.adstax.customerdomain.com",
  "port": 5672,
  "queue": "3f4ad08d-46e7-48cd-9686-e3822e34c810",
  "type": "amqp"
}

You can choose to only listen to a particular site or client by using the client and site attributes, for example: recommendations.adstax.customerdomain.com/recommendations/listen?client=client1&site=site1.

After this request, an amqp queue named 3f4ad08d-46e7-48cd-9686-e3822e34c810 has been created. This queue can be connected to using any AMQP clients compliant with AMQP 0-9-1 or a specific RabbitMQ client. The provided host and port should be used to connect to the broker. Note that the queue declaration must be passive, as the queue already exists in the broker. Once the queue has been bound at least once and no longer has clients associated with it, it will be destroyed, thus requiring another request to the /recommendations/listen endpoint for regeneration.

The broker requires authentication which is different for each ShiftForward DMP broker and will be supplied individually. Example of a set of credentials:

  • username: adstaxtest
  • password: 6hP3r4s7+2#7ac

Events

The messages that go into the queue are JSON objects with the same format as the responses to the user-based
recommendations endpoint, for example:

{
  "timestamp": "2015-09-08T15:09:14.188Z",
  "clientId": "client",
  "pid": null,
  "recommendedProducts": [
    "p-1",
    "p-2",
    "p-3",
    "p-4",
    "p-5"
  ],
  "uid": "aa6a5055-7855-4538-a55d-fa6c56640ff2",
  "siteId": "site"
}

Testing

In order to test the interaction with the queue, a simple command-line utility such as amqp-utils can be used. For the previous example, amqp-utils can be used as following to dequeue messages:

$ amqp-dequeue --host "mq.adstax.customerdomain.com" --port 5672 --user "adstaxtest" --password "6hP3r4s7+2#7ac aa6a5055-7855-4538-a55d-fa6c56640ff2"