Introduction
This article describes how to integrate the personalized recommendation functionality with any application using Magnet for Publishers Restful API.
Assumptions
- Indexing of content (Articles, videos, image galleries, etc) was done using either API calls or widgets placed on a web version of the application/service
- Client has obtained a valid CALK (Magnet’s Corporate API License Key) associated with their domain (URL address).
Integration on Article Page
Prerequisite
Article page/view must be associated with the same unique identifier (example: article UID, URL) used while indexing.
1. On Page Load
1.1 Call Tracking Event ‘A_PAGE_VIEW’ (see Page View Event details below)
1.2 Call Magnet’s API method ‘RecommendArticles’ (see RecommendArticles API details below)
2. On Recommended Article Click
2.1 Call Tracking ‘Event RCW_CLK’ (see Recommended Click Event details below)
Integration on Main Page (Homepage or Section page)
Prerequisite
Hompage or Section page/view must be associated with the any identifier (example: Section ID, Section name).
1. On Page Load
- Call Tracking Event ‘MP_PAGE_VIEW’ (see Page View Event details below)
- Call Magnet API method ‘RecommendArticles’ (see RecommendArticles API details below)
2. On Recommended Article Click
- Call Tracking Event ‘MP_RCW_CLK’ (see Recommended Click Event details below)
RecommendArticles API Method
Uri: https://magnetapi.klangoo.com/NewsAgencyService.svc/RecommendArticles
Request method : GET
|
Parameter |
Description |
|
calk |
A string containing your Magnet Corporate API License Key |
|
articleUID |
Unique ID representing the current article/page being read. |
|
userID |
A user unique identifier. Represents the user reading the article. |
|
showDetails |
(optional) Returns recommended documents details. 0 : show docID, articleUID, score, rank, insertDate (Default) 1 : same as value “0” plus title, URL, source, language 2 : same as value “1” plus snippet 3 : same as value “0” plus images 4 : same as value “2” plus images |
|
rulesGroupID |
ID of the group of rules to apply on the recommendation – In order to create rule group check Magnet Dashboard documentation. rulesGroupID has to be in the range [0 , 9999] |
|
maxReturnRows |
(optional) Maximum number of recommended documents to return. |
|
showCust |
(optional) Returns the custom fields of the article. Custom fields are special tags that you can include while indexing a page/article for filtering purposes. 0 – do not show custom fields (default) 1 – show custom fields |
|
langToShowOnly |
(optional) if the rulesGroup selected allows DynamicShowOnlyLanguages, then the recommendation will only include articles with the language you select using this parameter ex: “en”. Please check the supported languages document for all language codes. |
|
customFieldToShowOnly |
(optional) if the rulesGroup selected allows DynamicShowOnlyCustomField, then only return articles with specific Custom Field defined during indexing. Format: JSON => array of pairs of <string, string[]> |
|
snippetLength |
(optional) the length of the snippet of each recommended article (when showdetails is set) |
|
format |
(optional)The format of the response. The supported formats are “xml” and “json”. Default: “xml” |
|
timestamp |
(optional) required if ‘authenticate read’ is activated |
|
signature |
(optional) required if ‘authenticate read’ is activated |
Response:
|
XML tag |
Description |
|
status |
Indicates the status of the response. Possible values “OK” and “ERROR” |
|
error |
Indicates an error if one occurred (please check the error codes details table below) |
|
quota |
Indicates the number of remaining calls for this CALK |
|
relDocCount |
Related Content (article, video) count requested |
|
relatedDocuments |
Related Content (article, video) identified automatically by Magnet |
|
relDoc |
Related Content |
|
docID |
Magnet unique Content id |
|
insertDate |
Content last update date (set during the indexing process) |
|
title |
Content title (set during the indexing process) |
|
url |
Content URL (set during the indexing process) |
|
source |
Content source (set during the indexing process) |
|
snippet |
Short passage from the content retrieved |
|
images |
Thumbnail(s) associated with the content (set during the indexing process) |
|
lang |
Content language identified |
HTTP GET Format:
HTTP GET Example:
Tracking API Method
Uri: https://magnetrack.klangoo.com/
Request method : GET
|
Parameter |
Property Name |
Description |
|
c |
CALK |
Your Magnet Corporate API License Key |
|
e |
Event name/code |
Name of event |
|
u |
User ID |
Unique id of user. |
|
p |
Page ID (article or entity or main page) |
ArticleUID or Main page Id or entity Id (in case of an entity page) of the page where event happened. |
|
d |
Event Data |
(Optional) Clicked ArticleUID or entity id depending on event. |
|
l |
Application URL or window URL |
Application URL (example: http://application.com) or the window URL in the browser (using javascript window.location.href). The URL must be encoded. |
|
a |
Age |
Age accepts the following values: |
|
g |
Gender |
Gender accepts the following values: Male, Female |
|
o |
geolocation |
Geolocations can be of the format CityID/RegionID (see Geographical Criteria ID) or Country ISO Code (see ISO-3166-1 alpha-2) |
|
ran |
timestamp |
(Optional) This parameter is used to prevent the browser from fetching cached requests. Passing the timestamp should be enough to prevent the caching. |
Tracking Events
Page View Event
This event should be fired when an article page/main page is visited.
Event Code: A_PAGE_VIEW on Article Page, MP_PAGE_VIEW on Main Page
HTTP GET Format:
http://magnetrack.klangoo.com/?e=A_PAGE_VIEW&c=<calk>&p=<articleuid>&u=<userid>&l=<application url>
HTTP GET Example:
http://magnetrack.klangoo.com/?e=A_PAGE_VIEW&c=b1565a82-4ab3-46e7-88f7-d35ffe0e5f58&p=123456&u=john@test.com&l= http%3A%2F%2Fmyapplication.com
Recommended Article Click Event
This event should be fired when an article is clicked.
Event Code: RCW_CLK on Article Page, MP_RCW_CLK on Main Page
HTTP GET Format:
http://magnetrack.klangoo.com/?e=RCW_CLK&c=<calk>&p=<articleuid>&d=<clicked articleuid>&u=<userid>&l=<application url>
HTTP GET Example:
http://magnetrack.klangoo.com/?e= RCW_CLK&c=b1565a82-4ab3-46e7-88f7-d35ffe0e5f58&p=123456&d=55587&u=john@test.com&l= http%3A%2F%2Fmyapplication.com
Comments
0 comments
Article is closed for comments.