Download the PHP package lmc/matej-client without Composer

PHP API Client for Matej recommendation engine

Installation

Matej API client library is installed using Composer. Please be aware you must properly set-up autoloading in your project first.

We use HTTPlug abstraction so that the library is not hard coupled to any specific HTTP library, allowing you to use HTTP library which fits your needs (or maybe HTTP library you already use).

This means that besides the lmc/matej-client library itself you must install a package which provides php-http/client-implementation - see list of supported clients and adapters.

If you, for example, want to use Guzzle 6 as the underlying HTTP library, install the package like this:

Or if you want to use Guzzle 5 (note that unlike guzzle6-adapter, the one does not come with guzzlehttp/psr7, so you must install it as well):

Or if you want to use cURL client:

Usage

To start using Matej you will need your account id (database name) and secret API key - both of them must be obtained from LMC R&D team.

First create an instance of Matej object:

Now you can use request() method to use builders, which are available for each Matej endpoint and which will help you to assemble the request. Each request builder accepts via its methods instances of various Command(s) objects (see Lmc\Matej\Model\Command namespace). Refer to Matej documentation, code-completion in your IDE or examples below for more information.

Once finished with building the request, use send() method to execute it and retrieve the response:

See further below for examples of building request for each endpoint.

Processing the response

Once $response is filled with data from Matej (as in example above), you can now work with the response like this:

Sorting and Item Properties endpoints have syntax sugar shortcuts, which makes processing responses easier. See below for detailed examples.

Item properties setup (to setup your Matej's database)

Reset database

Database of test accounts (those ending with -test) could be reset via the API. Using this you can delete all data including database setup (item properties).

Reset data

Data (users and items) of test accounts (those ending with -test) could be reset via the API. Using this you can delete all data while keeping database setup (item properties, scenarios).

Send Events data to Matej

You can use events() builder for sending batch of following commands to Matej:

• Interaction via addInteraction() - to send information about interaction between user and item
• ItemProperty via addItemProperty() - to update item data stored in Matej database
• UserMerge via addUserMerge() - to merge interactions of two users and delete the source user

You can mix different command types in the same request. You can send up to 1 000 commands in a single request.

This endpoint has rate-limiting implemented. We constantly monitor workload on backend systems, and when the number of events in the queue crosses certain threshold, Matej API will start returning 429 errors. If that happens, you should resend the entire request later, as no commands were processed.

This has been implemented so that we don't lose any pushed data. Simple sleep of 100ms should be enough.

Merging users

You can merge users using the UserMerge command. The first argument is the target user ID and the second argument is the ID of source user. When you merge two users, Matej will move all interactions and history of the source user and assign them to the target user. The source user is then removed.

Optionally, you may send a third argument with a timestamp of when the merge happened.

The timestamp will be required in the future. We reccommend you to send it which will make future upgrades of the Matej client easier for you.

Requesting recommendations

You can request 4 types of recommendations from Matej. Each of them is represented by a specific recommendation command class:

• Items to user - UserItemRecommendation
• Items to item - ItemItemRecommendation
• Users to user - UserUserRecommendation
• Users to item - ItemUserRecommendation

For example, you can get recommendations for a single user using recommendation() builder. You can attach most recent interaction and user merge event to the request so that they're taken into account when providing recommendations.

You can also set more granular options of the recommendation command and overwrite Matej default behavior on per-request basis.

Each type of recommendation command supports different customization options. See table below.

Available recommendation attributes

From $response, you can also access rest of the data:

Recommendation response properties

Every item in Matej has its id, and optionally other item properties. These properties can be set up in item properties setup, and you can upload item data in the events request. This has major benefit because you can request these properties to be returned as part of your Recommendation Request.

We call them response properties. They can be specified by calling ->addResponseProperty() method or by calling ->setResponseProperties() method. Following will request an item_id, item_url, item_title:

If you don't specify any response properties, Matej will return an array of stdClass instances, which contain only item_id property. If you do request at least one response property, you don't need to mention item_id, as Matej will always return it regardless of the properties requested.

If you request an unknown property, Matej will return a BAD REQUEST with HTTP status code 400.

This way, when you receive recommendations from Matej, you don't need to loop the item_id and retrieve further information from your local database. It means, however, that you'll have to keep all items up to date within Matej, which can be done through events request.

Request item sorting for single user

Request item sorting for a single user. You can combine this sorting command with the most recent interaction and user merge event in one request, to make them taken into account when executing the item sorting.

From $response, you can also access rest of the data:

Request batch of recommendations/item sortings

Use campaign() builder to request batch of recommendations and/or item sorting for multiple users. A typical use case for this is generating email campaigns.

A/B Testing support

Recommendation and ItemSorting commands support optional A/B testing of various models. This has to be set up in Matej first, but once available, you can specify which model you want to use when requesting recommendations or sorting.

This is available for Recommendation, ItemSorting and Campaign requests:

If you don't provide any model name, the request will be sent without it, and Matej will use default model for your instance.

Typically, you'd select a random sample of users, to which you'd present recommendations and sorting from second model. This way, implementation in your code should look similar to this:

Model names will be provided to you by LMC.

Forgetting user data (GDPR)

Matej can "forget" user data, either by anonymizing or by deleting them. The right to erasure ("right to be forgotten") is part of General Data Protection Regulation in the European Union and can be implemented on your end using the forget() builder.

There are two ways how to remove user data, but both of them aren't reversible and you will not be able to identify the user ever again:

• Preferred way is to anonymize the user, which will randomly generate unique identifiers for all personal data, and change that identifier across all databases and logfiles. This way the users behavior will stay in Matej database, and therefore will continue to contribute to the recommendation model, but you won't be able to identify the user. Thus his profile will be effectively frozen (as no new interactions can come in.) New user id is generated server-side, so there is no going back after issuing the request.
• An alternate way is to delete the user, which will wipe their data from all databases in accordance with the Data Protection laws. This may affect the quality of recommendations, as the users behavior will be completely removed from all databases, and therefore their profile will not contribute to the recommendation model anymore.

Usually, though, the user will identify whether they want their data anonymized or deleted, and you have to adhere to their request.

To call the endpoint, use the forget() builder and append the users:

Exceptions and error handling

Exceptions are thrown only if the whole Request to Matej failed (when sending, decoding, authenticating etc.) or if the library is used incorrectly. If the request is successfully delivered to Matej, exception is not thrown even if any (or maybe all) of the submitted commands (which were part of the request) were rejected by Matej.

To check whether the whole Response (ie. all contained command responses) is successful, you thus MUST NOT rely on exceptions (because they won't be thrown - as stated above) but rather use Response::isSuccessful() method - see usage examples above.

If you want to check which individual CommandResponse was successful, you can check its status using CommandResponse::isSuccessful() method.

Exceptions occurring inside Matej API client implements Lmc\Matej\Exception\MatejExceptionInterface. The exception tree is:

Please note if you inject custom HTTP client (via $matej->setHttpClient()), it may be configured to throw custom exceptions when HTTP request fails. So please make sure this behavior is disabled (eg. http_errors option in Guzzle 6).

Troubleshooting RequestException

If RequestException is thrown when doing request to Matej, you may want to read the response body from the server to see the full error originating from Matej, so that you can troubleshoot the cause of the exception.

You can do it like this:

Changelog

For latest changes see Semantic Versioning.

Releasing new version

See RELEASE.md for step-by-step how to release new client version.

Running Tests

For each pull-request, unit tests, as well as static analysis and codestyle checks, must pass.

To run all those checks execute:

In case of codestyle violation you can run this command which will try to automatically fix the codestyle: