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 Opper Mail API.

Get suggestions

To get one reader's list of suggestions:

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 Opper Mail (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.
shuffle : Set to true to shuffle the suggestions. false by default.
start : Index of the first suggestion to return. Use it together with rows to implement client side pagination. Please contact support-ownpage@opper.io 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.
noredir : Set to true to avoid redirections when hitting recommended urls clicked by users (for mobile applications only). 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 :

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:

Without noredir parameter

{
   "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",
        "published_time":1676005200
      },
      {
        "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",
        "published_time":1676005200
      }]
   },
   "algo": "algo_hash123456789",
   "status": "OK"
}

With noredir parameter

{
   "result": {
      "recommendation": [{
        "guid": "123456",
        "url": "https://redir.ownpage.fr/vs/clients/789456123/bloc",
        "url_raw": "https://www.yoursite.fr/article/article1",
        "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",
        "published_time":1676005200
      },
      {
        "guid": "123456",
        "url": "https://redir.ownpage.fr/vs/clients/987654321/bloc",
        "url_raw": "https://www.yoursite.fr/article/article2",
        "title": "My other news of the day",
        "desc": "This is a super news",
        "image": "www.yoursite.fr/media/image2",
        "category_display": "News",
        "category": "News",
        "published_time":1676005200
      }]
   },
   "algo": "algo_hash123456789",
   "status": "OK"
}

Anonymous readers

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

<script type="text/javascript">
(function(){
    // Chargement de la librairie Opper Mail
    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 Opper Mail JS library (format JSONP):

<script type="text/javascript">
(function(){
    // Chargement de la librairie Opper Mail
    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 :

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 Opper Mail JS library)

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

<!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(){
    // Opper Mail 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>

Reader preferences

To get recommendations based on users' preferences, you need to:

add in the HTML of your articles a metadata ownpage:themes containing a list of themes covered by the article (comma-separated list)
set preferences of your users by calling Opper Mail API