Recommender API

Configuration API Docs
1

Marfeel recommender can be used via API whenever you don’t need html rendered recommendations. Common use cases would be personalizing push notifications, newsletters or infinite scroll.

Marfeel recommender API endpoint is https://experiences.mrf.io/recommenderexperience/render.json.

Before using this API, you will need to create a recommender experience using Marfeel Experience Manager, or via API, so that you can configure your recommendation engine along all its other available parameters.

The endpoint accepts the following query parameters:

  • id: the id of the recommender, which you can obtain from the url when accessing the experience in Experience Manager. This value is mandatory.
  • canonical_url: the url that you want recommended content to be similar to.
  • domain: the domain of your website. Only mandatory if canonical_urlis not provided.
  • client_id: Marfeel’s id of the user you want to send recommendations to. Not mandatory, but needed for personalization of the recommendations.
You can obtain any user Id using Marfeel SDK's getUserId method: 
<script>
window.marfeel.cmd.push(['compass', function(compass) {
	compass.getUserId().userIdPromise).then(
           (userid) =>  // do something ;
    )
}]);
</script>
If you are sending your own user ids to Marfeel using our User Subscriber functionality, you can directly use these same ids (subscriber ids) to get recommendations. You can also request any subscriber id from Marfeel SDK method compass.getSiteUserId().

Request example:

curl -G https://experiences.mrf.io/recommenderexperience/render.json \
	-d id=IL_rq6St2-fT2KNWFE8X1cwSQ \
	-d domain=touch.marfeel.com \
	-d client_id=dd1da57f-6fe1-4770-96cf-4b853a5990b1

Requests to this endpoint will return an array of recommendations in Json format. Each recommendation includes following fields:

  • url: The canonical url of the recommended article (string)
  • title: The title of the recommended article (string)
  • img: Main image of the recommended article (string)
  • authors: an array containing all author names for the recommended article (array of strings)
  • sections: an array containing all section names for the recommended article (array of strings)
  • publishTime: the publication date of the recommended article (string, date format yyyy-MM-dd hh:mm:ss)

All values are obtained from Marfeel’s analytics platform and are extracted as described here.

Response example

{
	"type":"RecommenderExperienceResponse",
	"recommendation":[
		{
			"url":"https://touch.marfeel.com/resources/blog/marfeels-response-to-confiants-privacy-policy-violation-allegations",
			"title":"Marfeel’s Response to Confiant’s Privacy Policy Violation Allegations ",
			"img":"https://marfeel.anticipa.io/public/uploads/default/image/blog/02_02_2022_12_15_08_blog_post_.jpeg",
			"authors":["Jon Doe"],
			"sections":["Audience", "Blog"],
			"publishTime":"2022-02-01 00:00:00"
		}
	]
}

Get recommendations from SDK

For other common use cases such as needing recommendations to render them client side, or adding pages in an infinite scroll mode, it may be more convenient to obtain them using a method available in Marfeel SDK.

In order to use it, insert the following script in your html:

window.marfeel.cmd.push(['experiences', (experiences) => {
	experiences.getRecommendations('<experience_id>') // insert your experience id here
		.then(recommendations => {
	             // do something with recommendations
		});
	}]);

Where recommendations will be an array with the same structure than recommendation in former example.

[
	{
		"url":"https://touch.marfeel.com/resources/blog/marfeels-response-to-confiants-privacy-policy-violation-allegations",
		"title":"Marfeel’s Response to Confiant’s Privacy Policy Violation Allegations ",
		"img":"https://marfeel.anticipa.io/public/uploads/default/image/blog/02_02_2022_12_15_08_blog_post_.jpeg",
		"authors":["Jon Doe"],
		"sections":["Audience", "Blog"],
		"publishTime":"2022-02-01 00:00:00"
	}
]
1 Like