MySmark API - MySmark

1. Introduction

MySmark API is composed of two parts:

The OAuth (v2) authorisation system (manages access control over the API)
The actual API (provides access over the the actual resources)

1.2 Downloads

We currently offer a Software Development Kit (SDK) for PHP.

Click here to download it as ~140KB …
gzTarball
(SHA256:405230de92366fc0f3ec8885fdcf2c91033e4bce3fbf7a47418a891c68c99d39 MD5:c736203e1a71a480233ccf9b884ff19a)
Zip archive
(SHA256:cd5ad9415c36f0c53585e536ca01ed1c3bb3375629d780981983c17c5db8930d MD5:3d4a4669c84afc73ea69a1120889cc5e).

2. OAuth (v2)

The only authorization type currently supported is via client_credentials.

You will use your client_id and client_secret (provided in the business page API Access section) to authenticate with MySmark server that will reply with an access_token that you can use to access your own resources (oauth_token parameter).

To get your API keys, log in MySmark then click on “Tools” in the navigation bar. Select the business account you wish to use for accessing the API, and in the home click on the “API Access” button on the sidebar.

This will open a dialog with three empty input fields. Insert the URL of your website in “OAuth redirect uri”, then click “Create/Update” to generate a pair of keys.

getApiToken

3. API

3.1 Overview

The only resources you can access for now via the API are the one your business account actually owns (your details and your events/objects).

All the parameters MUST be passed json_encoded (except the oauth_token).

3.2 Structure

The API URI is structured this way:

/OWNER_ID/COLLECTION/RESOURCE_ID

where:

OWNER_ID: is either your account ID or the alias “me”;

COLLECTION: is one of: “events” for accessing events, “objects” for accessing generic objects, “users” or “widgets”;

RESOURCE_ID: is the ID of the resource you want to access.

3.3 Methods

The supported methods are:

METHOD	OWNER_ID	COLLECTION	RESOURCE_ID
GET	Retrieve owner data	Retrieve a list of objects in this collection	Retrieve resource data
POST	Update owner data (allow partial update)	Add an entity to the given collection (see next chapter for entities data structure)	Update resource data (allow partial update)
DELETE	No	No	Delete the given resource (if it hasn't been smarked yet)

Notes:

In a POST call, you can only specify non-read only fields.

To create a new resource, you must specify at least all non nullable, non read only fields.

If a POST call creates a new resource, the ID will be returned. If a POST call updates a resource, the updated resource will be returned.

A DELETE call returns true on deletion, false with HTTP code 405: Method Not Allowed when unable to delete)

3.4 Data structure

Every entity in MySmark is a Smarkable. A Smarkable is something that can be smarked, and this is why you will find some properties such as “singleVote” or “smarked” in the entities described in this chapter.

Following is the structure for the 5 entities currently supported (Account, Object, Event, Widget, User):

3.4.1 Account (only available through /me call)

Parameter name	Data type	Nullable	Read only
id	String	No	Yes
type	String = "Account"	No	Yes
created	Integer (UNIX timestamp)	No	Yes
modified	Integer (UNIX timestamp)	No	Yes
name	String	No	No
description	String	Yes	No
url	String (valid url)	Yes	No
image	String (valid image url)	Yes	No
singleVote	Boolean = false	No	Yes
protected	Boolean = true	No	Yes
requiresSpecialPermissions	Boolean = false	No	Yes
publicStats	Boolean = false	No	Yes
expires	Integer (UNIX timestamp)	Yes	Yes
smarked	Boolean = false	No	Yes
privileges	Integer	No	Yes

Examples:

Retrieve you account information:

GET /me

Update your account information:

POST /me
Attached data:
{
    "name" => "My new name",
    "description" => "My new description",
    "url" => "http://www.mywebsite.com",
    "image" => "http://www.mywebsite.com/john/picture.png"
}

3.4.2 Object (‘objects’ collection)

Parameter name	Data type	Nullable	Read only
id	String	No	Yes
type	String = "Object"	No	Yes
created	Integer (UNIX timestamp)	No	Yes
modified	Integer (UNIX timestamp)	No	Yes
name	String	No	Only after creation
description	String	Yes	No
url	String (valid url)	Yes	No
image	String (valid image url)	Yes	No
singleVote	Boolean	No	No
protected	Boolean	No	Yes
requiresSpecialPermissions	Boolean	No	Only after creation
publicStats	Boolean	No	No
expires	Integer (UNIX timestamp)	Yes	No
smarked	Boolean	No	Yes
category	String (lowercase)	No	Only after creation
externalReference	String (a reference in your database)	Yes	No
json	String (free JSON string that you can use if you need to store additional data)	Yes	No
parameters (DEPRECATED)	Array	No	No
location (DEPRECATED)	Object { "name": String }	Yes	No
smarkOnImageBackground	String (valid image url)	Yes	No
smarkOnImagePin	String (valid image url)	Yes	No

Note: the “objects” collection will also return a field called “page”, containing an Integer value to use to get the next page’s objects. The field is empty if there aren’t more objects to return.

Examples:

Retrieve your objects list:

GET /me/objects

Retrieve the next page of objects, if the previous call returned a page number (as a timestamp):

GET /me/objects
Attached data:
{
    "page" => {TIMESTAMP}
}

Create a new object that expires on the 6th of November 2015 and can be voted multiple times by the same user:

POST /me/objects
Attached data:
{
    "name" => "Web Summit 2015",
    "category" => "conference"
    "singleVote" => false,
    "expires" => 1446768000
}

Retrieve a specific object:

GET /me/objects/{OBJECT_ID}

Update the name of an object:

POST /me/objects/{OBJECT_ID}
Attached data:
{
    "name" => "My new name"
}

Delete an object:

DELETE /me/events/{OBJECT_ID}

3.4.3 Event (‘events’ collection)

This is a special category of objects (see previous chapter) that MySmark uses as default in the Tools page of your account when creating a new Object manually. In the same page you will see every kind of objects anyway, included the ones created via API.

An Event is an Object with category “Event” and a start and end timestamp in the json field.

It is recommended to use the Object collection instead of this one. However, if you need to use it, the “events” collection is available and has the same fields and methods of the “objects” one.

Examples:

Create an event that starts on the 3th of November and ends on the 6th of the same month:

POST /me/events
Attached data:
{
    "name" => "Web Summit 2015",
    "singleVote" => false,
    "json" => {
        "starts" => 1446508800
        "ends" => 1446768000
    }
}

3.4.4 Widget (‘widgets’ collection)

The widget collection is not yet writable, meaning that you are only allowed to read the widgets available to your account.

Parameter name	Data type	Nullable	Read only
_id	String (12 byte hex)	No	Yes
preview	String (url)	No	Yes
type	Integer	No	Yes
name	String	No	Yes

Note: the “widgets” collection will also return a field called “types”, containing an object with the association between the widget type ID and the mnemonic name for it, for example:

"types": {
    "0": "E-Rose",
    "1": "N-Parametric",
    "6": "Spider-Net",
    "8": "Gradient",
    "9": "Thanks-Page"
}

3.4.5 User (‘users’ collection)

Parameter name	Data type	Nullable	Read only
name	String	No	Only after creation
description	String	Yes	Only after creation
email	String (valid email address)	No	Only after creation
gender	String (one single character, 'm' or 'f')	No	Only after creation
birthdate	String ("dd/mm/yyy" format)	No	Only after creation
country	String (two-letters country code)	No	Only after creation
image	String (valid image url)	Yes	Only after creation
url	String (valid url)	Yes	Only after creation
expires	String (UNIX timestamp)	Yes	Only after creation

For selected partners MySmark allows API access to a special “users” collection.

This collection allows customers to create(***) linked users on our database. The generated users are MySmark users with a link to your business account, and the user logged in MySmark will see your name on their “Networks Manager”.

Users can also choose to disconnect from your network, deleting the link with your account. In this case, you won’t be able to make any operation on them anymore. A link can be re-established creating a new linked user with the same email address. On user login through a transaction (see proper chapter in Keywords), they will see a dialog that notifies them to link again.

Notes:

If there is an “image” field specified, the URL will be used as profile picture for the user. It is suggested to use your company’s logo, or the picture in your system for that user. If an “image” is not specified, MySmark will check the email address to see if a Gravatar applies. If nothing is found then the MySmark default picture will be set.

You CAN’T modify a linked user for now.

You are responsible to check if your user accepts the MySmark Terms of Service.

(***)Please read about end-of-life.

Examples:

A user in your system is identified by the ID “100”, create for them a profile on MySmark to let them use the service:

POST /me/users/100
Attached data:
{
    "name": "Name Surname",
    "email": "user@email.com",
    "gender": "m",
    "birthdate": "18/02/1964",
    "country": "IE",
    "image": "http://www.yourwebsite.com/users/100/picture.png"
}

If successful, the above request will return the following object:

{
    "user_id": 20803,
    "ext_id": 100
}

Where “user_id” is MySmark’s internal user ID, and “ext_id” is your reference to the user from your system.

If you’ll need to make any other action on the linked user, you must refer to them using the ID from your system, not the MySmark one.

If you make more than one POST call to the same resource ID, MySmark will always return the same result, there is no need to check if you already registered a user to avoid doing it twice.

A GET request will either return the same result, or a HTTP code 404 if not found.

3.5 Keywords

We are now introducing the concept of keyword.

A keyword is a modifiers that allows specific actions to be performed on a subset of collections or resources.

Keywords must always be added as the last part of the url:

/OWNER_ID/KEYWORD

/OWNER_ID/COLLECTION/KEYWORD

/OWNER_ID/COLLECTION/ID/KEYWORD

3.5.1 Steps (‘steps’ keyword)

Applicable to the following collections: objects, events.

Returns the widgets associated with the given object or event in the following format:

{
    "steps": Object[] // Ordered array of steps
}

Where each step is an object with the following format:

{
    "step_id": ID,            // id of the widget, or "emo" string for the emotional rose
    "optional_flag": Boolean, // if the step can be skipped by the user, true means an optional step while false a mandatory step
    "type": Integer           // widget type (see widget collection 3.4.3 for supported types)
}

Examples:

Retrieve the widgets used in an object:

GET /me/objects/{OBJECT_ID}/steps

Create a new object and assign to it a known list of widgets:

POST /me/objects     // With data attached (see 3.4.2) will return an OBJECT_ID for the newly created object
WIDGETS_ID = Array[  // Prepare the array with the widgets id
    'steps' => Array[
        Array['step_id' => {WIDGET_ID_1}],
        Array['step_id' => {WIDGET_ID_2}],
        ...
        Array['step_id' => {WIDGET_ID_n}],
    ]
]
POST /me/objects/{OBJECT_ID}/steps // Finally set it to the object with WIDGETS_ID attached

3.5.2 Transactions (‘transaction’ keyword)

A transaction can be created for linked users in the users collection. Refer to the Users collection chapter to know more about them.

A POST request will create a new transaction for the given user, allowing the customer to automatically log in MySmark the user and attach additional parameters to that user smarks.

After the request, you will receive a transaction hash to use as a GET parameter in our embed widget iframe, to automatically log in the user in MySmark. Transactions are one-time only and have an expiration time.

Examples:

Request a transaction for your user “100”, that was already created as seen in the Users collection chapter:

POST /me/users/100/transaction
Attached data (OPTIONAL):
{
    "params" : {
        "param1": "string",
        "param2": false,
        "somethingelse": 145
    }
}

This will generate the following response:

{
    "hash": "ed79629f1cba7eb954ce88bda87623a4" // Always in the response
    "params" : {                               // Optional parameters, if specified in the request
        "param1": "string",
        "param2": false,
        "somethingelse": 145
    }
    "user_id": 20803,
    "expires": 1410271524
}

At this point you can embed the MySmark widget with the standard link, adding the “user_signon” parameter containing the hash you just received.

https://www.mysmark.com/embed.php?id={OBJECT_ID}&user_signon={TRANSACTION_HASH}

When a user loads that URL, they will be logged in MySmark as the user “100” you registered in our system.

Please note: the first person visiting that link will be logged in MySmark, you are responsible to publish the right link with the proper transaction hash to your users.

3.5.3 Smark as a User (‘smark’ keyword)

You can request our system to generate a smark on behalf of a User in your users collection. The specified user will find the smark in their account, as if they did it.

You may want to generate a smark for a user for a number of reasons:

to save the vote done by the user through a Combi-Action™ Button on your website,
to integrate your own widget with the MySmark framework, mapping each vote from your widget to our supported emotions,
to simply track your users’ choices and save each vote in a MySmark Object.

Every smark created in this way in relation to an object can be seen and exported through our statistical tools.

A POST request will create a new smark for a given user in relation to an object in MySmark. Every parameter is read only for now after the first creation. Non nullable fields are mandatory.

Parameter name	Data type	Nullable	Description
refObject	Integer	No	The id of the Object to smark.
title	String	Yes	The title of the smark. Usually set by the end user.
comment	String	Yes	The comment for the smark. Usually set by the end user.
emotion	Numeric, must be between 0 and 31 both included	Yes	The id of the smarked emotion. See attachments after table. Omit this field to create a neutral, non-emotional vote. If field is present and valid, the smark will be "emotional"
emotionLabel	Integer, must be a supported EmotionLabel id	Yes	The id of the EmotionLabel. See attachments after table. This field is used only if an "emotion" was set.
emotionCaption	Integer, must be a supported EmotionCaption id	Yes	The id of the EmotionCaption. See attachments after table. This field is used only if an "emotion" was set.
value	String	Yes	Any extra data related to this smark, for example mouse coordinates on a click action and similar.

After the request, a JSON representation of the smark will be returned on success.

The following files are only for your reference to see what numeric id to use for emotion, emotionLabel and emotionCaption using the English language as example. The end user will see text strings localized to their language and gender. All text strings are guaranteed to exist for the English and Italian languages.

Download the list of supported Emotions with their numeric identifiers [CSV file]

Download the list of supported Emotion Labels with their numeric identifiers [CSV file]

Download the list of supported Emotion Captions with their numeric identifiers [CSV file]

In case of an emotional vote, each of the 32 emotions has a default label and an empty caption. You can set a different label and caption using the files above. You can’t for example smark a certain emotion using the label of a different one. Labels and captions, if specified, must belong to the smarked emotion.

Notes:

You can request a smark at any given time, but it’s recommended that a smark is the result of a user action on your website.

A user linked to your network doesn’t need to be logged in with a transaction for you to request a smark on their behalf. As long as you know the identifier for a user linked to your network, you can request a smark at any time you like.

You must make sure the selected user can read and smark the specified object, otherwise an error will be thrown. When creating an object, keep an eye for the protected and the expires flags which could prevent users to smark it.

Examples:

We have a Combi-Action™ button on our website linked to the search feature. Our user “100” searches the keyword “prices” and clicks a side button with label “Just curious”. Create a smark for this action in order to track it properly.

POST /me/users/100/smark
Attached data:
{
    "refObject" => {OBJECT_ID},
    "title" => "Just curious",
    "comment" => "I searched for: prices",
    "value" => "prices"
}

Where {OBJECT_ID} is the id of the object we created just to collect user’s smarks in our search feature. We set a title and comment to display the smark to the user in a nice and comprehensible way, then we also set the value with something we will only see, for example the searched keyword. The smark in this case is non emotional.

Another example.

We created our own emotional widget with only three emotions in it: excited, hesitant and worried, plus a comment section. Our usual user identified by the number “100” writes a comment and selects excited, make a smark to track this information.

POST /me/users/100/smark
Attached data:
{
    "refObject" => {OBJECT_ID},
    "comment" => "{COMMENT_FROM_FORM}",
    "emotion" => 0,
    "emotionLabel" => 7
}

The request above will smark the specified object with Joy, since the emotion id 0 corresponds to that. We also specified an emotionLabel, the user won’t see the label Joy then but the label excitement.

You can also specify a caption, choosing one from the supported ones for Joy in this case (Emotion_id = 0 in the EmotionCaption.csv file).

The statistics in MySmark will show a smark under the “Joy” emotion, while a more deep analysis done by exporting the full CSV for that object will reveal all the information about the label and the comment. It is also recommended to use the “value” parameter to store technical data that the user won’t see, but you might need. Anything in that field will be found in the exported CSV.

3.5.4 Smarks list (‘smarks’ keyword)

Applicable to the following collections: objects, events.

Returns the smarks done on an object, plus a global smark counter, in the following format:

{
    "totalSmarks": Integer,
    "smarks": Object[],
    "nextPage": Integer or Null
}

The totalSmarks will hold the total number of smarks done on that object.

smarks is a list of Smark objects. A maximum of 5 smarks for each request will be returned, and they will be from the most recent to the oldest. If the smarks are less than five, you have reached the last page.

nextPage is a pointer to help you get the remaining smarks. If this value is null, you have reached the last page.

Examples:

Retrieve the most recent smarks for an object you own:

GET /me/objects/{OBJECT_ID}/smarks

Retrieve the following page of smarks for the same object:

GET /me/objects/{OBJECT_ID}/smarks
Attached data:
{
    "page" : "value of nextPage in the previous request"
}