Skip to content

Smart Sections

Smart sections are personalized suggestions you can directly integrate on your website. Each user will receive articles he is likely to be interested in, using the recommendations of our AI, based both on his behaviour and on the content he is reading.

You will learn here how to add this feature on your website using the Ownpage API.

Get suggestions

To get one reader's list of suggestions:

1
GET --header "referer:URL_OF_MY_ARTICLE" https://recos.ownpage.fr/v1/clients/BLOCK_KEY/users/USER_ID/recommendations?rows=NUMBER_OF_RECOS

With :

  • BLOCK_KEY : the API key for your smart section, given by Ownpage (NB: this is not the CLIENT_TRACKING_KEY used for navigation tracking)
  • USER_ID : the reader ID.
  • NUMBER_OF_RECOS : the number of suggestions to return.
  • URL_OF_MY_ARTICLE : replace it by the URL of the page currently being read. We use the referer header to contextualize the recommendations.

Optional parameter :

  • excluded[] : Array of URL to exclude from the suggestions.
  • start : Index of the first suggestion to return. Use it together with rows to implement client side pagination. Please contact support@ownpage.fr to know your maximum number of suggestions per user.
  • redir_https : Set to true to build redirection URLs that remain in https. false by default.

Example : to get the first two suggestions for the user 123456 excluding the url http://www.canardmag.com/article-123.html and http://www.canardmag.com/article-456.html :

1
GET https://recos.ownpage.fr/v1/clients/abcdef/users/123456/recommendations?rows=6&excluded[]=http%3A%2F%2Fwww.canardmag.fr%2Farticle-123.html&excluded[]=http%3A%2F%2Fwww.canardmag.fr%2Farticle-456.html

Example of return in JSON:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
   "result": {
      "recommendation": [{
        "guid": "123456",
        "url": "https://redir.ownpage.fr/vs/clients/789456123/bloc",
        "title": "My super news of the day",
        "desc": "This is really a super news",
        "image": "www.yoursite.fr/media/image1",
        "category_display": "News",
        "category": "News",
      },
      {
        "guid": "123456",
        "url": "https://redir.ownpage.fr/vs/clients/987654321/bloc",
        "title": "My other news of the day",
        "desc": "This is a super news",
        "image": "www.yoursite.fr/media/image2",
        "category_display": "News",
        "category": "News",
      }]
   },
   "algo": "algo_hash123456789",
   "status": "OK"
}

Display infos from your Facebook page

If your block is configured to include facebook infos (email us at support@ownpage.fr), only articles published on your facebook page will be recommended. Facebook infos are available in the API in the additional_data key. To display the title or image of the article, you can choose between the one used on your site and the one used on your facebook page.

Note that the same article can be published on multiple facebook pages, so in the JSON, the facebook key is an array.

Example of return in JSON:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "result": {
    "recommendation": [
        {
            "guid": "123456",
            "url": "http://www.canardmag.fr/news/Fabian-frei-a-mayence/568746",
            "title": "Fabian Frei à Mayence",
            "desc": "Le Suisse Fabian Frei quitte le FC Bâle pour rejoindre...",
            "image": "http://medias.canardmag.fr/img-photo-jpg/fabian-frei-[...].jpg",
            "category": "Sport",
            "additional_data": {
              "facebook": [{
                "page_id": "123456789",
                "page_logo": "http://medias.canardmag.fr/logo.jpg",
                "image": "http://medias.canardmag.fr/img-photo-jpg/fabian-frei-[...].jpg",
                "url": "http://www.canardmag.fr/news/Fabian-frei-a-mayence/568746",
                "message": "Message facebook du community manager",
                "name": "Fabian Frei à Mayence",
                "description": "Le Suisse Fabian Frei quitte le FC Bâle pour rejoindre...",
                "reactions": {
                  "like": 15,
                  "comment": 7,
                  "share": 11,
                  "wow": 3,
                  "haha": 1,
                  "sad": 2,
                  "love": 0,
                  "angry": 10,
                  "thankful": 1
                }
              }]
            }
        }
    ]    
  },
  "algo": "egzg54s13568e",
  "status": "OK"
}

Anonymous readers

For not identified readers, the USER_ID variable should be filled by the Ownpage cookie. This cookie is accessible with the Ownpage JS library :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<script type="text/javascript">
(function(){
    // Chargement de la librairie Ownpage
    function loadOwnpageScript(e){var t="https://script.ownpage.fr/v1/",a=document.createElement("script"),n=document.getElementsByTagName("script")[0];a.type="text/javascript",a.defer=1,a.async=1,a.src=t+"ownpage.js",a.onload=e,a.readyState?a.onreadystatechange=function(){("loaded"==a.readyState||"complete"==a.readyState)&&(a.onreadystatechange=null,e&&"function"==typeof e&&e())}:a.onload=function(){e&&"function"==typeof e&&e()},n.parentNode.insertBefore(a,n)}

    loadOwnpageScript(function () {
       var userId = Ownpage.getAnonymousUserId();
    });
})();
</script>

Display (JSONP)

To display suggestions with the Ownpage JS library (format JSONP):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<script type="text/javascript">
(function(){
    // Chargement de la librairie Ownpage
    function loadOwnpageScript(e){var t="https://script.ownpage.fr/v1/",a=document.createElement("script"),n=document.getElementsByTagName("script")[0];a.type="text/javascript",a.defer=1,a.async=1,a.src=t+"ownpage.js",a.onload=e,a.readyState?a.onreadystatechange=function(){("loaded"==a.readyState||"complete"==a.readyState)&&(a.onreadystatechange=null,e&&"function"==typeof e&&e())}:a.onload=function(){e&&"function"==typeof e&&e()},n.parentNode.insertBefore(a,n)}

    loadOwnpageScript(function () {
       Ownpage.getRecommendations(BLOCK_KEY, USER_ID, DISPLAY_FUNCTION_NAME, NUMBER_OF_RECOS, EXCLUDED_ARTICLES);
    });
})();
</script>

With :

  • DISPLAY_FUNCTION_NAME : name of the display function.
  • USER_ID : User Id. It can be empty, undefined or null if the reader is anonymous.
  • Other parameters are described above.

Note: The referer header is included automatically by Ownpage.js in the request with a front-end integration. On a back-end integration, you need to include it in the header of your GET request. This allow us to serve contextualized recommendations, based on the user but also on the page currently read.

The display function is a javascript function called when the suggestions are returned by the API. This function should be accessible in the global scope. The unique parameter of the function is the array of suggestions computed for the user.

Example of display function :

1
2
3
4
5
6
7
function displayRecommendations(recommendations) {
    var recommendations = recommendations.result.recommendation
    for (var i = 0; i < recommendations.length; i++) {
        var recommendation = recommendations[i]
        // Affichage de la recommandation
    }
}

Complete example (with Ownpage JS library)

HTML page for the user 123456 with tracking and suggestion display :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<!DOCTYPE html>
<html>
<head>
    <title>Sample recommendations</title>
</head>
<body>

<ul id="ownpage-recommendations"></ul>

<script type="text/javascript">
// Display function  should be in the global scope
function displayRecommendations(recommendations) {
    var recommendations = recommendations.result.recommendation;
    for (var i = 0; i < recommendations.length; i++) {
        var list = document.getElementById("ownpage-recommendations");
        var newLI = document.createElement("li");
        var newText = document.createTextNode(recommendations[i].title);
        newLI.appendChild(newText);
        list.appendChild(newLI);
    }
}

(function(){
    // Ownpage library loading
    function loadOwnpageScript(e){var t="https://script.ownpage.fr/v1/",a=document.createElement("script"),n=document.getElementsByTagName("script")[0];a.type="text/javascript",a.defer=1,a.async=1,a.src=t+"ownpage.js",a.onload=e,a.readyState?a.onreadystatechange=function(){("loaded"==a.readyState||"complete"==a.readyState)&&(a.onreadystatechange=null,e&&"function"==typeof e&&e())}:a.onload=function(){e&&"function"==typeof e&&e()},n.parentNode.insertBefore(a,n)}

    loadOwnpageScript(function () {
        Ownpage.trackPage(CLIENT_TRACKING_KEY, 123456);
        Ownpage.getRecommendations(BLOCK_KEY, 123456, "displayRecommendations", 10);
    });
})();
</script>
</body>
</html>

Comments