Multiplayer APIs: Multiplayer Assign | Documentation

Multiplayer Assign API

A world is a set of end users and their shared runs.

The Multiplayer Assign API allows you to assign end users to worlds, creating new worlds as appropriate, automatically.

Note that this different from the Multiplayer World API's POST method for adding an end user to a world and automatically assigning a role. The Multiplayer World API requires that the world already be created, and only assigns a single end user.

In contrast, the Multiplayer Assign API creates new worlds automatically, based on the project-level world configuration, and by default assigns all end users. (It can also assign only particular end users.)

Because multiplayer worlds link end users, the Multiplayer Assign API is only used with Authenticated projects, that is, projects with end users and groups.

The Multiplayer Assign API supports the following methods:

POST: Auto-assign all users to worlds
POST: Assign specific users to worlds

Automatically Assigning All End Users to Worlds

Method: POST

URI: /v2/multiplayer/assign/

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

Body: JSON object containing the account, project, group, and optionally maxUsers

Return Status:

200: Successful creation of worlds and assignment of end users in this group to those worlds.
400: Unable to complete assignment.

Return Body: Array of world records for the worlds created.

Example:

curl -X POST \
    'https://api.forio.com/v2/multiplayer/assign/' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"account": "acme-simulations", "project": "supply-chain-game", "group": "fall2014-seminar", "maxUsers": 4}'

Example Response:

[
    {
        "account": "acme-simulations",
        "users": [
            {
                "lastName": "Smith",
                "status": "new",
                "index": 0,
                "userId": "b1c19dda-2d2e-4777-ad5d-3929f17e86d3",
                "userName": "jsmith"
            },
            // other end users assigned to this world
        ],
        "created": "2015-04-06T18:33:47.000Z",
        "project": "supply-chain-game",
        "group": "fall2014-seminar",
        "complete": true,
        "lastModified": "2015-04-06T18:33:48.000Z",
        "name": "World001",
        "id": "5522d18bfac2a46606000036",
        "roles": [],
        "optionalRoles": []
    },
    // world records for other worlds created
]

Notes:

In the header, the access token can be the user access token of a team member developing this project, or the project access token for the project.
In the body,
- The account field is the Team ID.
- The project field is the Project ID.
- The group field is the Group Name.
- The maxUsers is optional if you have specified roles in your world configuration; otherwise it is required. That is, you must specify either roles or maxUsers in order to automatically assign end users to worlds.
Only standard end users are included in this autoassignment. End users that are facilitators are not assigned to worlds.
Only end users that are currently active are included in this autoassignment.
When end users are assigned to worlds, a message is automatically posted to the world channel.

Assigning Specific End Users to Worlds