forio Toggle navigation

Presence API

The Epicenter Presence API allows you to determine whether specific end users in your project are currently online.

This is useful primarily for multiplayer worlds. For example, you can use the Presence API to determine whether to assign end users to worlds, and how to display their status in a chat system using the push channel.

The Presence API supports the following methods:

Background: When the Presence API is Called

The Presence API is called automatically by Epicenter in several circumstances:

  • When a user comes online, POST is called and notification is sent to the group channel and world channel (see more on channels). Additionally, notification is sent to the presence channel, which is an Epicenter.js abstraction: special type of group channel that only listens to presence notifications.
  • When a user goes offline, DELETE is called and notification is sent to the group channel and world channel (see more on channels). Additionally, notification is sent to the presence channel, which is an Epicenter.js abstraction: special type of group channel that only listens to presence notifications.
  • The online / offline status is determined by:
    • The end user's explicit connection to or disconnection from a channel. (Internally, a heartbeat is used to determine whether the user has gone offline explicitly, in advance of being automatically timed out.)
    • The end user's work on a run, including: creating a run, replaying a run, calling an operation, setting a variable, or retrieving a run or its variables.

POST: Creating a Message about the Presence of a User

Method: POST

URI: /v2/presence/{account id}/{project id}/{group name}/{user id}

Headers:

  • Authorization: Bearer{access token}
  • Content-Type: application/json

Request Body: A JSON object with the message and optionally a ttlSeconds.

Return Status:

  • 204: Successful creation of a presence record for this user.

Return Body: The presence record just created.

Example:

curl -X POST \
    'https://api.forio.com/v2/presence/acme-simulations/supply-chain-game/fall-seminar/6cf9ca31-9d7a-45d6-b081-1d9069cdcc50' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --header 'Content-Type: application/json' \
    --data '{ "message": "online" }'

Example Response:

{
    "lastModified": "2015-06-30T19:06:12.000Z",
    "message": "online",
    "userId": "6cf9ca31-9d7a-45d6-b081-1d9069cdcc50",
    "ttlSeconds": 600
}

Notes:

  • In the URI,
    • The account id is the Team ID (for team projects) or User ID (for personal projects).
    • The project id is the Project ID.
    • The group name is the name of the group, listed under [Project Name] > Groups.
    • The user id is the unique identifier of the user record.
  • In the header, the access token can be the user access token for the end user in question, or another access token with write permissions for the group (e.g. project access token, team member token).
  • The existence of a presence record for a user indicates that the user is currently online. (The content of the message field is by convention "online", but the content is not used to indicate presence for a user.)
  • Creating a new record immediately overwrites the previous one; for each user, there are always either zero or one presence records.
  • Each presence record is automatically deleted a predetermined amount of time after its creation. In the request body, the optional ttlSeconds determines how long until this automatic deletion occurs; the default is still under discussion.

GET: Retrieving Information about the Presence of Users

Retrieving Presence Information for Specific Users

Method: GET

URI:

  • One user: /v2/presence/{account id}/{project id}/{group name}?userId={user id}
  • Multiple users: /v2/presence/{account id}/{project id}/{group name}?userId={user id}&userId={user id}

Headers:

  • Authorization: Bearer{access token}

Request Body: None.

Return Status:

  • 200: Successfully returned any presence records associated with these users.

Return Body: Array of presence records for the requested users.

Example: 

curl -G \
    'https://api.forio.com/v2/presence/acme-simulations/supply-chain-game/fall-seminar?userId=6cf9ca31-9d7a-45d6-b081-1d9069cdcc50' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9'

Example Response: 

[
    {
        "lastModified": "2015-06-30T19:06:12.000Z",
        "message": "online",
        "userId": "6cf9ca31-9d7a-45d6-b081-1d9069cdcc50",
        "ttlSeconds": 600
    }
]

Notes:

  • In the URI,
    • The account id is the Team ID (for team projects) or User ID (for personal projects).
    • The project id is the Project ID.
    • The group name is the name of the group, listed under [Project Name] > Groups.
    • The userId is the unique identifier of the user record. If searching for multiple user ids, note that the query parameter userId needs to be repeated.
  • In the header, the access token can be the user access token for the end user in question, or another access token with read permissions for the group (e.g. another end user, or a facilitator).
  • The existence of a presence record for a user indicates that the user is currently online. Creating a new record immediately overwrites the previous one; for each user, there are always either zero or one presence records.

Retrieving All Online Users

Method: GET

URI: /v2/presence/{account id}/{project id}/{group name}

Headers:

  • Authorization: Bearer{access token}
  • Optional: Range: records {i}-{j}

Request Body: None.

Return Status:

  • 200: Successfully retrieved all records.
  • 206: Successfully retrieved the partially complete response, for example if you request records 0-20 and there are 35 records.
  • 416: No records are found in a given search range (e.g. Range: records 10-15 when there are only 8 records)

Return Body: Array of presence records for the all users in the requested scope.

Example: 

curl -G \
    'https://api.forio.com/v2/presence/acme-simulations/supply-chain-game/fall-seminar' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9'

Example Response: 

[
    {
        "lastModified": "2015-06-30T19:06:12.000Z",
        "message": "online",
        "userId": "6cf9ca31-9d7a-45d6-b081-1d9069cdcc50",
        "ttlSeconds": 600
    },
    // other presence records, if any
]

Notes:

  • In the URI,
    • The account id is the Team ID (for team projects) or User ID (for personal projects).
    • The project id is the Project ID.
    • The group name is the name of the group, listed under [Project Name] > Groups.
  • In the header, the access token can be the user access token for the end user in question, or another access token with read permissions for the group (e.g. another end user, or a facilitator).
  • The existence of a presence record for a user indicates that the user is currently online. This query returns all records for the requested team / project / group scope, which is all online end users.

DELETE: Removing the Presence Record of a User

Method: DELETE

URI: /v2/presence/{account id}/{project id}/{group name}/{user id}

Headers:

  • Authorization: Bearer{access token}

Request Body: None

Return Status:

  • 204: Successfully deleted presence record.

Return Body: None

Example: 

curl -X DELETE \
    https://api.forio.com/v2/presence/acme-simulations/supply-chain-game/fall-seminar/6cf9ca31-9d7a-45d6-b081-1d9069cdcc50' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

None.

Notes:

  • In the URI,
    • The account id is the Team ID (for team projects) or User ID (for personal projects).
    • The project id is the Project ID.
    • The group name is the name of the group, listed under [Project Name] > Groups.
  • In the header, the access token can be the user access token for the end user in question, or another access token with write permissions for the group (e.g. project access token, team member token).
  • The existence of a presence record for a user indicates that the user is currently online. Deleting the record means the user is now considered offline by Epicenter.