Communicating student experiences and interactions
For more information about understanding and communicating student experiences through events, please see: Sending Events
In this section:
POST /registrations/{id}/ungraded-events
Creates a new ungraded event for the given registration. This is used to record work that a student has done against a teaching module which does not assess knowledge.
Note that events (including ungraded events) should only be sent on atoms, and never on bundles. If a student completes atoms in a bundle, then a separate event must be sent for each atom.
This endpoint must be called by the partner admin user or the user associated with the registration.
| Parameter | Type | Optional | Description |
|---|---|---|---|
| id | uuid | No | The ID of the registration with which the student’s interactions are associated. |
| Parameter | Type | Optional | Description |
|---|---|---|---|
| duration | duration | Yes | The best estimate of the number of milliseconds the student gave primary attention to the module. This is required if Active Time or Time Spent will be requested for as part of Analytics. |
| module_id | uuid or string | No | The ID of the instructional atom with which the user interacted. May be the atom’s UUID or its “mref-“ prefixed partner label. |
| interaction_end_time | datetime | No | The time this interaction ended. |
| is_complete | boolean | Yes | This field is not used but is preserved for backwards compatibility, and should always be present and set to ‘true’ in all implementations. If a student has not fully consumed a piece of content, then no event should be sent at all. |
| goal_id | uuid | Yes | The ID of the goal on which the user was working when this interaction took place. May be omitted if the interaction occurred outside the context of an adaptive assignment. |
Sample Request Body
{
"duration": 312904,
"module_id": "mref-c3f6b4f2-4496-4e46-a48b-885b9a44c86b",
"interaction_end_time": "2012-11-19T16:30:31-04:00",
"is_complete": "true",
"goal_id": "57466e95-6019-498d-9c42-9180aa663304"
}
POST /registrations/{id}/graded-events
Sends a new graded event for the given registration. This is used to record work that a student has done against a module which assesses a learner.
Note that events (including graded events) should only be sent on atoms, and never on bundles. If a student completes atoms in a bundle, then a separate event must be sent for each atom.
This endpoint must be called by the partner admin user or the user associated with the registration.
| Parameter | Type | Optional | Description |
|---|---|---|---|
| id | uuid | No | The ID of the registration with which the student’s interactions are associated. |
| Parameter | Type | Optional | Description |
|---|---|---|---|
| duration | duration | Yes | The best estimate of the number of milliseconds the student gave primary attention to the module. This is required if Active Time or Time Spent will be requested for as part of Analytics. |
| module_id | uuid or string | No | The ID of the atom with which the user interacted. May be the atom’s UUID or its “mref-“ prefixed partner label. |
| interaction_end_time | datetime | No | The time this interaction ended. |
| is_correct | boolean | No | true if the learner demonstrated the knowledge assessed by the item, false otherwise. |
| is_complete | boolean | Yes | This field is not used but is preserved for backwards compatibility, and should always be present and set to ‘true’ in all implementations. If a student has not answered an assessment module, then no event should be sent. If the student has answered an assessment module, but the partner software does not yet know if the assessment is correct or incorrect, then it should wait to send an event until it has determined correctness. |
| instance_hash | string | Yes | A string that uniquely identifies which instance of an algorithmic question was shown, within the context of the module_id. This field should only be provided when sending an event for algorithmic question. |
| goal_id | uuid | Yes | The ID of the goal on which the user was working when this interaction took place. May be omitted if the interaction occurred outside the context of an adaptive assignment. |
Sample Request Body
{
"duration": 12294,
"module_id": "mref-f7e86f46-b81f-4ef7-aac1-e4fdf5e7612e",
"interaction_end_time": "2012-11-19T16:30:31-04:00",
"is_correct": true,
"is_complete": true,
"instance_hash": "6,7",
"goal_id": "57466e95-6019-498d-9c42-9180aa663304"
}
POST /registrations/{id}/recommendation-followed-events
Records that the user followed the given recommendation.
This endpoint must be called by the partner admin user or the user associated with the registration.
| Parameter | Type | Optional | Description |
|---|---|---|---|
| id | uuid | No | The ID of the registration with which the student’s interactions are associated. |
| Parameter | Type | Optional | Description |
|---|---|---|---|
| module_id | uuid | No | The ID of the module with which the user interacted. May be the module’s UUID or its “mref-“ prefixed partner label. |
| time_followed | datetime | No | Time the recommendation was followed. |
| recommendation_id | long | No | The ID of the recommendation that was followed. Note: recommendation IDs are integers and not UUIDs. |
Sample Request Body
{
"recommendation_id": 9289981383,
"module_id": "mref-f7e86f46-b81f-4ef7-aac1-e4fdf5e7612e",
"time_followed": "2012-11-19T16:30:31-04:00"
}
POST /registrations/{id}/focus-events
Notify that the student is focusing on a specific goal.
This endpoint is deprecated and should not be used in new integrations. Goals will automatically focus whenever a recommendation is requested for the goal.
This endpoint must be called by the partner admin user or the user associated with the registration.
| Parameter | Type | Optional | Description |
|---|---|---|---|
| id | uuid | No | The ID of the registration with which the student’s interactions are associated. |
| Parameter | Type | Optional | Description |
|---|---|---|---|
| goal_id | uuid | No | ID of the goal the student is focusing on. |
Sample Request Body
{
"goal_id": "57466e95-6019-498d-9c42-9180aa663304"
}
POST /registrations/{id}/batch-events
Creates a new batch event for a given registration. Batched events allow API clients to combine multiple events into one request so that multiple events can be posted at once.
This endpoint must be called by the partner admin user or the user associated with the registration.
| Parameter | Type | Optional | Description |
|---|---|---|---|
| id | uuid | No | The ID of the registration with which the student’s interactions are associated. |
| Parameter | Type | Optional | Description |
|---|---|---|---|
| goal_id | uuid | Yes | The ID of the goal for which this batch of events is to be sent. The presence of a goal ID is equivalent to sending a focus event for that goal before sending the remainder of the events in the batch. |
| events | object[] | No | List of events to be sent as a batch. Graded, ungraded, and recommendation followed events can be included. Events must be listed in reverse chronological order (most recent event first.) |
| events[].type | string | No | Type of event, can be one of “recommendation-followed”, “graded-events”, or “ungraded-events” |
| ignore_invalid_module_ids | boolean | Yes | When set to true, the module IDs will not be validated. This allows events to be sent (and ignored) for content that may not have been processed for adaptivity. When set to false, if at least one of the module IDs is invalid (not recognized by Knewton) the request will produce an error. Defaults to false. Note that the endpoint will give no indication of whether or not events were ignored, so the use of this flag is greatly discouraged. |
Sample Request Body
{
"goal_id": "e69b1375-a5ae-4392-a40c-579ecd8dcebc",
"events": [
{
"type": "recommendation-followed",
"recommendation_id": 9289981383,
"module_id": "mref-f7e86f46-b81f-4ef7-aac1-e4fdf5e7612e",
"time_followed": "2012-11-19T16:30:31-04:00"
},
{
"type": "graded-events",
"duration": 12294,
"module_id": "mref-f7e86f46-b81f-4ef7-aac1-e4fdf5e7612e",
"interaction_end_time": "2012-11-19T16:30:31-04:00",
"is_correct": true,
"is_complete": true,
"instance_hash": "6,7",
"goal_id": "57466e95-6019-498d-9c42-9180aa663304"
},
{
"type": "ungraded-events",
"duration": 312904,
"module_id": "mref-c3f6b4f2-4496-4e46-a48b-885b9a44c86b",
"interaction_end_time": "2012-11-19T16:30:31-04:00",
"is_complete": "true",
"goal_id": "57466e95-6019-498d-9c42-9180aa663304"
}
]
}