PUT login/apps/clustering/rules

From Social ID Developers
Revision as of 20:24, 7 June 2019 by Renato.neves (Talk | contribs)
Jump to: navigation, search

Contents

Description

Updates login app clustering rules.

When a user logs in using his credential, these rules will be evaluated by the clustering engine, which will determine the likelihood for each feature label, according to the classifier used to evaluate the feature.

For example, the feature could be "music", and the labels could be "rock", "pop" and "blues". The clustering engine goal is to determine the user's interest likelihood for each label from a given feature. Considering the previous example, an example of likelihoods could be: rock - 0.5, pop - 0.2, blues - 0.3, that is, the user seems to be more interested on "rock" music, with 50% probability.

The clustering results for each user can be retrieved using the API GET login/users/:user_id/clustering/features.

Resource URL

  PUT https://api.socialidnow.com/v1/marketing/login/apps/clustering/rules

Parameters

JSON Parameters

rules required a hash containing the features and parameters used in the clustering engine.
features required a hash containing the classifier definition for each feature.
parameters optional a hash containing global parameters used by the classifiers.

Features

Each feature is composed by the labels you want to classify the user and the classifier used to evaluate the user data.

The feature is defined as follow:

labels required an array of labels
name required a string to identify the label
[extra] optional extra parameters used by the classifier.
classifier required a hash containing the classifier parameters
type required the classifier algorithm
[extra] optional extra parameters used by the classifier.

Classifiers

The following classifiers types are available:

likes

This classifier uses full text search on user's Facebook likes based on keywords defined for each label.

Label extra parameters:

keywords required an array of keywords. Each keyword defined as words are searched using OR and keywords defined as phrases are searched using AND. Example: ["rock", "roll", "surf music"] will be searched for (rock OR roll) AND "surf music".

Classifier extra parameters:

categories optional an array of Facebook likes categories. Example: ["Musician/Band", "Music", "Music award"]. Note: the Facebook provides likes categories names according to the user's defined language, so you may need to define the list of categories using multiple languages (in English and Portuguese, for example).
threshold optional requires that the number of likes from the defined categories is at least the percentage defined in the threshold, considering all likes. Ex: 0.2, that is, 20% of likes should be in the categories defined by the parameter "categories".

Global Parameters

The following parameters can be defined in the global hash "parameters", or inside each classifier definition, in order to reduce the scope:

excluded_words optional an array of keywords. The keywords should be words and not phrases. Example: ["hate", "bad", "ugly"]


The parameters defined inside a classifier will replace the global ones for that classifier. Example: if excluded_words is defined in both global and classifier parameters, only the excluded_words defined in the classifier scope will be used, discarding the global one (there is no merge between global and classifier excluded words).

Authentication

This API requires Social Login App authentication. See Authentication.

Response

Response Status

ok (200) The request was successful.
unauthorized (401) The authentication is wrong. See Authentication.
unprocessable_entity (422) Validation error in the parameters.
internal_server_error (500) An unknown error happened.

Examples

Request

Use the JSON saved on rules.json file to update the clustering rules for the login app 138:

curl -iX PUT 'https://api.socialidnow.com/v1/marketing/login/apps/clustering/rules' \
-H 'Content-type: application/json' \
--data @rules.json \
--user 138:e8b9ca24f1b590af67e6271297d6e1f7226625d61c5b5daa1b2f215464e292cf

Example for rules.json:

{
 "rules": {
   "features": {
     "music": {
       "labels": [
         {
           "name": "rock",
           "keywords": [
             "rock"
           ]
         },
         {
           "name": "pop",
           "keywords": [
             "pop"
           ]
         },
         {
           "name": "blues",
           "keywords": [
             "blues"
           ]
         },
         {
           "name": "country",
           "keywords": [
             "country"
           ]
         }
       ],
       "classifier": {
         "type": "likes",
         "categories": [
           "Musician/Band",
           "Music",
           "Music award"
         ],
         "threshold": 0.1,
         "excluded_words": [
           "soul"
         ]
       }
     },
     "movies": {
       "labels": [
         {
           "name": "drama",
           "keywords": [
             "drama"
           ]
         },
         {
           "name": "comedy",
           "keywords": [
             "comedy",
             "comedia"
           ]
         },
         {
           "name": "sci-fi",
           "keywords": [
             "sci-fi",
             "scifi"
           ]
         },
         {
           "name": "horror",
           "keywords": [
             "horror",
             "terror"
           ]
         },
         {
           "name": "adventure",
           "keywords": [
             "adventure",
             "aventura"
           ]
         }
       ],
       "classifier": {
         "type": "likes",
         "categories": [
           "Movie",
           "Movie genre",
           "Movies/music"
         ],
         "threshold": 0
       }
     }
   },
   "parameters": {
     "excluded_words": [
       "hate",
       "bad",
       "ugly"
     ]
   }
 }
}

Response

Response Headers

HTTP/1.1 200 Ok
Status: 200
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox