1. Watershed LRS
  2. Getting Data in and Out of Watershed
  3. xAPI Data Sources

How do I author video xAPI statements?

Avatar
Peter Dobinson

Many people say that video content is the most important part of their learning ecosystem, but they don’t know the best way to design good statements from their activity providers track video usage. The challenge is that (as of January 2019) there is no established norm for implementing video statements with xAPI. There is a profile being worked on and if video is important to you you should become involved in the group working to create it. Until then we’ve outlined some suggested approaches you can take

This guide offers some advice, resources, and examples to help you implement xAPI in your activity provider so that the data works well with Watershed’s reports.

How xAPI statements about videos are different

xAPI statements about video should follow all the usual advice about implementing xAPI plus a few additional points:

xAPI registry video recipe

The xAPI video recipe (you need to click on the table to see the full recipe) was created when the xAPI specification was still being developed as a best practise example of how to track learners watching a video using xAPI.

 

It is normally the place to start when designing your implementation as it is the closest there is currently to a standard implementation method. It utilizes the following statements/verbs:

  • Play. Sent when the video play button is pressed. It also sends the video timestamp when the statement was triggered as a context extension in ISO8601 format. This means you can see not only when a video was first viewed, but any subsequent event in your reporting.
  • Pause. Triggered when the video is paused either when requested by the user, or when the video reaches its end. It sends the video timestamp when the statement was triggered as a context extension as a float or ISO8601 format.
  • Watch. This is sent when the video is paused, and contains the video timestamp in ISO8601 format that it started playing, and when it was paused using the starting-point and ending-point extensions.
  • Skip. Sent when the user fast forwards or rewinds through the video via any method. It is similar to watched in that it sends the starting point and ending point of the action. This means that the ending point can in the event of the user skipping back be before the starting point.
  • Complete. Sent when the video is advanced to the end, and sends the time the video was completed in ISO8601 format as a context extension ending-point.

Other considerations

  • All statements must have the video activity as the 'object'
  • The length of the video in should be sent in every statement using the extension duration.

A real world implementation

As mentioned in the introduction the lack of standardisation means that various learning record providers implement video using very different methods, some based on the video profile and some that don’t.

Kaltura

One of the most common sources that sends video related statements to Watershed is Kaltura, a video learning platform. It utilises the following events:

  • Logged in. Sent when the learner authenticates to the Kaltura platform.
  • Viewed. Used when a learner views a video category/channel page.
  • Liked. Used to show a learner has liked/favorited a piece of video content. Uses the verb http://activitystrea.ms/schema/1.0/like.
  • Commented. This verb show a learner has commented on a video, however it does not include the content of the comment. If implementing this the content could be useful, especially when investigating learner experience analytics.
  • Shared. Triggered when a learner clicks on the share link in the Kaltura UI.
  • Played and watched video. Kaltura uses two different verbs to show video watches/progress:
    • Played is triggered when a learner views any video in the system. It also uses an extension to show that the progress through the video is 0%:

      "result": {
      
      "extensions": {
      
      "https://w3id.org/xapi/cmi5/result/extensions/progress": "0"
      
      }
    • Watched is then used with the same extension and triggered at quarterly intervals as the video content is watched by the learner:

      "result": {
      
      "extensions": {
      
      "https://w3id.org/xapi/cmi5/result/extensions/progress": "75%"
      
      }
  • Completion of video quizzes. Kaltura has a function where a questions can be presented alongside a video. These statements are a hybrid of a video and a quiz statement that you would get from an LMS or an elearning course, it's just the object definition type is set to video not quiz. I've included an example of it in example statements.

You can have a further look at some examples of Kaltura's statements at the end of this article. Kaltura's implementation of xAPI whilst not following the xAPI video recipe is a really good real world implementation that works well with Watershed’s dashboards. Once the data is connected to Watershed you can quickly begin to see which content is the most liked, commented or used. Which videos are performing badly, or just not being watched and which users are most active in the platform. You can see these reports in our article on connecting Kaltura to Watershed.

Other points you need to consider

The points in this sections are things you should consider when implementing video in xAPI, the answers to which are not set in stone. You need to work out how you might go about implementing these considerations in your implementation.

Session ID’s

What should the session ID in context.registration reflect? In reality is up to you, but it could relate to an individual video (see the the initialized and terminated statements idea below) or an entire login session from authentication to expiry. The latter could be to begin to discover how videos are related, especially if you are sending viewed statements when a learner views a video allowing you to recommend videos to learners based on the watch history of others.

The definition of complete/incomplete

What does complete mean? In the same way that an elearning course will often only trigger a completed statement when all screens have been viewed you may want your video to do the same and trigger a completed statement when the entire video has been viewed. If you do implement this approach you need to carefully consider what constitutes a learner completing a video. Does the learner have to watch every frame? Can they fast forward it and still complete it? Do they have to do it in one session?

How verbose do you need to be?

When designing your implementation consider how verbose you want your statements (and therefore your video players event capability) to be. Some system only report the fact that the user has watched the video, however for your data analysis to be truly useful you may want to consider also tracking using extensions:

  • How often did they pause, restart, rewind, fast-forward and scrub through the video during the session? This information is really useful when delving into learner experience analytics. If a video is paused often, and then re-wound it could well be it is difficult to understand. If it is fast forwarded often it could be too simplistic, or just boring the viewers! Scrubbing (especially if the timestamps the user scrubbed to and from are recorded) could show a section of the video that needs a rework if there are lots of scrubbing events with similar timestamps. These are only a few you should also consider what other events mean. Things like lots of learners turning volume up or turning on the captions for a video, this could mean the audio track is too quiet.
  • Consider adding in additional details like the video quality used, there viewport and if the full screen video option is used and sending them as extensions. This can help if you to see if you need full size 4k video, or if smaller files that load faster will suffice.
  • Learners language preferences, and the available audio/subtitle tracks. This can help you to see where you might have gaps in the translations of your videos.

As mentioned in the introduction there is quite a bit of work going on around xAPI's use in video. The xAPI video profile community of practice have thought about how to better implement xAPI in video. At the time of writing (January 2019) we don't recommend implementing their work but if video is important to you, you should be involved in the community of practice developing this profile.

Example statements

xAPI video recipe example

Completed

This statement demonstrates how to show completion when following the xAPI video recipe.

 {
	"actor": {
		"mbox": "mailto:video.user@example.com",
		"name": "Video User",
		"objectType": "Agent"
	},
	"verb": {
		"id": "http://adlnet.gov/expapi/verbs/completed",
		"display": {
			"en-US": "completed"
		}
	},
	"timestamp": "2019-02-06T14:05:25.158Z",
	"object": {
		"definition": {
			"type": "http://adlnet.gov/expapi/activities/video",
			"name": {
				"en": "An introduction to corporate financial reporting metrics"
			},
			"description": {
				"en-US": "An introduction from our head of finance into the metrics we report on as a buisness."
			}
		},
		"id": "http://video.examplecdn.net/v/corporatefinaicialreportingmetrics.mp4",
		"objectType": "Activity"
	},
	"result": {
		"completion": true,
		"extensions": {
			"http://id.tincanapi.com/extension/ending-point": "T1H3M55S"
		}
	},
	"context": {
		"contextActivities": {
			"category": [
                            {
                              id": "http://id.tincanapi.com/recipe/video/base/1",
                              "type": "http://id.tincanapi.com/activitytype/recipe"			}]
		            },
		"extensions": {
			"https://w3id.org/xapi/video/extensions/session-id": "7a1f8a80-8b62-4cf5-9165-a4976280f6c4",
			"http://id.tincanapi.com/extension/duration": "T1H3M55S"
		},
		"registration": "3da7f040-2a1b-11e9-b210-d663bd873d93"
	},
	"id": "40db117a-2a1b-11e9-b210-d663bd873d93"
}

xAPI Video COP example

Initialized

This example is based on the work of the xAPI video profiles community of practice.

 {
    "actor": {
        "mbox": "mailto:video.user@example.com",
        "name": "Video User",
        "objectType": "Agent"
    },
    "verb": {
        "id": "http://adlnet.gov/expapi/verbs/completed",
        "display": {
            "en-US": "completed"
        }
    },
    "timestamp": "2019-02-06T14:05:25.158Z",
    "object": {
        “id”: “https://examplevideosite.com/media/01898390”,
        "definition": {
            "type": "http://adlnet.gov/expapi/activities/video",
            "name": {
                "en-US": “An introduction to corporate financial reporting metrics“
            },
            "description": {
                "en-US": "An introduction from our head of finance into the metrics we report on as a buisness."
            }
        },
        "id": "http://video.examplecdn.net/v/corporatefinaicialreportingmetrics.mp4",
        "objectType": "Activity"
    },
    "result": {
        "completion": true,
        "extensions": {
            "http://id.tincanapi.com/extension/ending-point": "T1H3M55S"
        }
    },
    "context": {
        "contextActivities": {
            "category": [
              {
                 "id": "http://adlnet.gov/expapi/activities/video"           
             ]
        },
        "extensions": {
            "https://w3id.org/xapi/video/extensions/session-id": "7a1f8a80-8b62-4cf5-9165-a4976280f6c4",
            "http://id.tincanapi.com/extension/duration": "T1H3M55S"
        },
        "registration": "3da7f040-2a1b-11e9-b210-d663bd873d93"
    },
    "id": "40db117a-2a1b-11e9-b210-d663bd873d93"
}

Kaltura examples

Logged in

 
{
  "id": "d8115d08-23cb-47f5-a9bb-5d17a42dfcb1",
  "actor": {
	"objectType": "Agent",
	"name": "Video User",
	"mbox": "mailto:video.user@example.com"
  },
  "verb": {
    "id": "https://brindlewaye.com/xAPITerms/verbs/loggedin/",
    "display": {
      "en": "logged in to"
    }
  },
  "object": {
    "objectType": "Activity",
    "id": "https://example.mediaspace.kaltura.com",
    "definition": {
      "name": {
        "en": "Example Channel"
      },
      "type": "http://activitystrea.ms/schema/1.0/application"
    }
  },
  "context": {
    "contextActivities": {
      "category": [
        {
          "objectType": "Activity",
          "id": "http://tincan-definitions.kaltura.com/products/mediaspace/1",
          "definition": {
            "type": "http://id.tincanapi.com/activitytype/source"
          }
        }
      ]
    }
  },
  "version": "1.0.0"
}

Viewed

 
{
  "id": "fbea8f92-3983-4649-8134-4ef8eb44fd94",
  "actor": {
	"objectType": "Agent",
	"name": "Video User",
	"mbox": "mailto:video.user@example.com"
  },
  "verb": {
    "id": "http://id.tincanapi.com/verb/viewed",
    "display": {
      "en": "viewed"
    }
  },
  "object": {
    "objectType": "Activity",
    "id": "https://example.mediaspace.kaltura.com/default/channels/view/channelid/75565771",
    "definition": {
      "name": {
        "en": "Example Channel"
      },
      "type": "http://id.tincanapi.com/activitytype/category"
    }
  },
  "context": {
    "contextActivities": {
      "category": [
        {
          "objectType": "Activity",
          "id": "http://tincan-definitions.kaltura.com/products/mediaspace/1",
          "definition": {
            "type": "http://id.tincanapi.com/activitytype/source"
          }
        }
      ]
    }
  },
  "version": "1.0.0"
}

Liked

 
{
  "id": "ac61b2f3-1131-4ce9-8464-55ef30b23dea",
  "actor": {
	"objectType": "Agent",
	"name": "Video User",
	"mbox": "mailto:video.user@example.com"
  },
  "verb": {
    "id": "http://activitystrea.ms/schema/1.0/like",
    "display": {
      "en": "liked"
    }
  },
  "object": {
    "objectType": "Activity",
    "id": "https://example.mediaspace.kaltura.com/media/t/4_nz21dsov",
    "definition": {
      "name": {
        "en": "Example video name"
      },
      "type": "http://adlnet.gov/expapi/activities/video"
    }
  },
  "context": {
    "contextActivities": {
      "other": [
        {
          "objectType": "Activity",
          "id": "https://example.mediaspace.kaltura.com",
          "definition": {
            "name": {
              "en": "Example Channel"
            },
            "type": "http://activitystrea.ms/schema/1.0/application"
          }
        }
      ],
      "category": [
        {
          "objectType": "Activity",
          "id": "http://tincan-definitions.kaltura.com/products/mediaspace/1",
          "definition": {
            "type": "http://id.tincanapi.com/activitytype/source"
          }
        }
      ]
    },
    "extensions": {
      "http://tincan-definitions.kaltura.com/extensions/context/video-mode": "VOD"
    }
  },
  "version": "1.0.0"
}

Commented

 
{
  "id": "59737cba-5ef9-4d4e-a539-f5439c3bd5e1",
  "actor": {
	"objectType": "Agent",
	"name": "Video User",
	"mbox": "mailto:video.user@example.com"
  },
  "verb": {
    "id": "http://adlnet.gov/expapi/verbs/commented",
    "display": {
      "en": "commented on"
    }
  },
  "object": {
    "objectType": "Activity",
    "id": "https://example.mediaspace.kaltura.com/media/t/1_jv678i26#comment-2_4mjcrrgj",
    "definition": {
      "name": {
        "en": "Example comment name - Video ID"
      },
      "type": "http://activitystrea.ms/schema/1.0/comment"
    }
  },
  "context": {
    "contextActivities": {
      "parent": [
        {
          "objectType": "Activity",
          "id": "https://example.mediaspace.kaltura.com/media/t/1_jv678i26",
          "definition": {
            "name": {
              "en": "Example video name"
            },
            "type": "http://adlnet.gov/expapi/activities/video"
          }
        }
      ],
      "other": [
        {
          "objectType": "Activity",
          "id": "https://example.mediaspace.kaltura.com",
          "definition": {
            "name": {
              "en": "Channel name"
            },
            "type": "http://activitystrea.ms/schema/1.0/application"
          }
        }
      ],
      "category": [
        {
          "objectType": "Activity",
          "id": "http://tincan-definitions.kaltura.com/products/mediaspace/1",
          "definition": {
            "type": "http://id.tincanapi.com/activitytype/source"
          }
        }
      ]
    },
    "extensions": {
      "http://tincan-definitions.kaltura.com/extensions/context/video-mode": "VOD"
    }
  },
  "version": "1.0.0"
}

Shared

 
{
  "id": "e2c11c58-045d-4fbe-9042-3f2aeb54920e",
  "actor": {
	"objectType": "Agent",
	"name": "Video User",
	"mbox": "mailto:video.user@example.com"
  },
  "verb": {
    "id": "http://adlnet.gov/expapi/verbs/shared",
    "display": {
      "en": "shared"
    }
  },
  "object": {
    "objectType": "Activity",
    "id": "https://example.mediaspace.kaltura.com/media/t/1_jv678i26",
    "definition": {
      "name": {
        "en": "Example video name"
      },
      "type": "http://adlnet.gov/expapi/activities/video"
    }
  },
  "context": {
    "contextActivities": {
      "other": [
        {
          "objectType": "Activity",
          "id": "https://example.mediaspace.kaltura.com",
          "definition": {
            "name": {
              "en": "Example channel name"
            },
            "type": "http://activitystrea.ms/schema/1.0/application"
          }
        }
      ],
      "category": [
        {
          "objectType": "Activity",
          "id": "http://tincan-definitions.kaltura.com/products/mediaspace/1",
          "definition": {
            "type": "http://id.tincanapi.com/activitytype/source"
          }
        }
      ]
    },
    "extensions": {
      "http://tincan-definitions.kaltura.com/extensions/context/video-mode": "VOD",
      "http://id.tincanapi.com/extension/target": {
        "definition": {
          "name": {
            "en": "Target name"
          },
          "type": "http://id.tincanapi.com/activitytype/category"
        },
        "id": "https://example.mediaspace.kaltura.com/default/channels/view/channelid/75565771",
        "objectType": "Activity"
      }
    }
  },
  "version": "1.0.0"
}

Played

 
{
  "id": "49a56db6-7913-4fa1-9992-40ef982c1567",
  "actor": {
	"objectType": "Agent",
	"name": "Video User",
	"mbox": "mailto:video.user@example.com"
  },
  "verb": {
    "id": "http://activitystrea.ms/schema/1.0/play",
    "display": {
      "en": "played"
    }
  },
  "object": {
    "objectType": "Activity",
    "id": "https://example.mediaspace.kaltura.com/media/t/1_jv678i26",
    "definition": {
      "name": {
        "en": "Example video name"
      },
      "type": "http://adlnet.gov/expapi/activities/video"
    }
  },
  "result": {
    "extensions": {
      "https://w3id.org/xapi/cmi5/result/extensions/progress": "0"
    }
  },
  "context": {
    "contextActivities": {
      "other": [
        {
          "objectType": "Activity",
          "id": "https://example.mediaspace.kaltura.com",
          "definition": {
            "name": {
              "en": "Example channel name"
            },
            "type": "http://activitystrea.ms/schema/1.0/application"
          }
        }
      ],
      "category": [
        {
          "objectType": "Activity",
          "id": "http://tincan-definitions.kaltura.com/products/mediaspace/1",
          "definition": {
            "type": "http://id.tincanapi.com/activitytype/source"
          }
        }
      ]
    },
    "extensions": {
      "http://tincan-definitions.kaltura.com/extensions/context/video-mode": "VOD"
    }
  },
  "version": "1.0.0"
}

Watched

 
{
  "id": "8c837d99-b5be-4415-ae7b-03d14711d62d",
  "actor": {
	"objectType": "Agent",
	"name": "Video User",
	"mbox": "mailto:video.user@example.com"
  },
  "verb": {
    "id": "http://activitystrea.ms/schema/1.0/watch",
    "display": {
      "en": "watched"
    }
  },
  "object": {
    "objectType": "Activity",
    "id": "https://example.mediaspace.kaltura.com/media/t/1_jv678i26",
    "definition": {
      "name": {
        "en": "Example video name"
      },
      "type": "http://adlnet.gov/expapi/activities/video"
    }
  },
  "result": {
    "extensions": {
      "https://w3id.org/xapi/cmi5/result/extensions/progress": "75"
    }
  },
  "context": {
    "contextActivities": {
      "other": [
        {
          "objectType": "Activity",
          "id": "https://example.mediaspace.kaltura.com",
          "definition": {
            "name": {
              "en": "Example channel name"
            },
            "type": "http://activitystrea.ms/schema/1.0/application"
          }
        }
      ],
      "category": [
        {
          "objectType": "Activity",
          "id": "http://tincan-definitions.kaltura.com/products/mediaspace/1",
          "definition": {
            "type": "http://id.tincanapi.com/activitytype/source"
          }
        },
        {
          "objectType": "Activity",
          "id": "https://example.mediaspace.kaltura.com/default/channels/view/channelid/75565771",
          "definition": {
            "name": {
              "en": "Example channel name"
            },
            "type": "http://id.tincanapi.com/activitytype/category"
          }
        }
      ]
    },
    "extensions": {
      "http://tincan-definitions.kaltura.com/extensions/context/video-mode": "VOD"
    }
  },
  "version": "1.0.0"
}

Completion of video quiz

This example demonstrates how to combine a video, and a quiz into a single statement. This is a good starting point for any other kind of interactive video elements.

{
	"id": "3b2639df-e4b7-4b12-9ea8-27b6dbfdefde",
	"actor": {
		"objectType": "Agent",
		"name": "Video User",
		"mbox": "mailto:video.user@example.com"
	},
	"verb": {
		"id": "http://adlnet.gov/expapi/verbs/completed",
		"display": {
			"en": "completed"
		}
	},
	"object": {
		"objectType": "Activity",
		"id": "https://example.mediaspace.kaltura.com/media/t/2_4h32ft8u",
		"definition": {
			"name": {
				"en": "demonstration.mp4 - Quiz"
			},
			"type": "http://adlnet.gov/expapi/activities/video"
		}
	},
	"result": {
		"score": {
			"scaled": 1,
			"raw": 2,
			"min": 0,
			"max": 2
		},
		"completion": true
	},
	"context": {
		"contextActivities": {
			"other": [{
				"objectType": "Activity",
				"id": "https://example.mediaspace.kaltura.com",
				"definition": {
					"name": {
						"en": "Example channel"
					},
					"type": "http://activitystrea.ms/schema/1.0/application"
				}
			}],
			"category": [{
				"objectType": "Activity",
				"id": "http://tincan-definitions.kaltura.com/products/mediaspace/1",
				"definition": {
					"type": "http://id.tincanapi.com/activitytype/source"
				}
			}]
		},
		"extensions": {
			"http://tincan-definitions.kaltura.com/extensions/context/video-mode": "VOD"
		}
	}
}
Was this article helpful?
0 out of 0 found this helpful

Related articles

If you can't find what you need or you want to ask a real person a question, please contact customer support.