Standalone Lesson Webhooks

Note: this article is intended for software developers, and probably won't be readable for most users. If you are not comfortable writing code, this section is not for you!

Overview

While generally standalone lessons will not save any viewing data or question responses, there is a way for advanced users with programming experience to store data from standalone lessons.

Before downloading a standalone lesson, you can set up a webhook URL, where the data will be sent to as the lesson is viewed. To set a webhook URL, just click the webhook icon to the right of the standalone lesson button, enter your webhook URL, and click Save. You can also just add it as a property "webhookURL" in the config.json file of any standalone lesson.

The optional webhook sends back a variety of analytical data that you can collect and process on your own server. This data is sent via AJAX POST requests to the web address you entered when downloading the lesson.

You will need to use the lesson itself (the data.json file in the data folder of your download) to decode some of the information sent back.

Each call will include the tourId (a unique identifier for the lesson) and either a type or elementType property (except for Discussion comments which are a special case). It will also include a viewerName, however this will always be set to "Anonymous User" for the standalone lesson since users will never be logged-in. The tourId will map to the _id property of the lesson in your data.json file.

Viewing Data

If the type property is set, you are receiving viewing data. The type property can be set to either "tourStarted" or "progress":

  • tourStarted - A call with the tourStarted type is sent once each time the lesson is started (when the start button is clicked). The JSON for this might look like:

        {

            type: "tourStarted",

            tourId: "5659862fa186afb063315e8f",

viewerName: "Anonymous user"

       }

  • progress - This call includes all the viewer specific viewing data collected during a viewing of the lesson. There are three properties to take a look at. First is the fingerprint. This is a unique identifier for the browser being used to access the lesson. For viewers using a shared computer it is recommended they each use a different browser to help make sure data isn’t overridden. Next is the extraTime field. This is the total time the lesson has been played since the last progress update (they generally occur every 3-30 seconds). The final property of note is the events array. This is the full collection of events that have occurred during the current page visit, they might include each time the user skips forward or backward (and which clip it occurred in, see data.json and match to clips._id), if the user got to the end of the tour, and which specific 5 second spans have been viewed.

Example -

       {

type: "progress",

tourId: "5659862fa186afb063315e8f",

extraTime: 10.022,

events: [

       0: { name: "spanViewed", data: { tourSecondsMark: 5 } },

       1: { name: "spanViewed", data: { tourSecondsMark: 10 } },

       2: { name: "clipSkippedForward", data: { clipId: "5671aaee677269395a000100" } },

       3: { name: "clipSkippedBackward", data: { clipId: "4771aaed6bb269395a00ef0f" } },

       4: { name: "tourFinished" }

],

fingerprint: "PzJpy1Gdo7ei7ax9QohnotiJGsc=",

viewerName: "Anonymous user"

       }

Question Responses

Responses to questions will be sent to the same endpoint, but will include an elementType property instead of a type property.

Multiple choice elements include the text of the choice and the choice ID, which can can be matched up with data from the data.json file. An example:

{

     elementType: "MultipleChoice",

     tourId: "5659862fa186afb063315e8f",

     elId: "5659766b8a4e7e5480000152",

     viewerName: "Anonymous user",

     fingerprint: "PzJpy1Gdo7ei7ax9QohnotiJGsc=",

     text: "the fourth choice",

     choice: "665376738a4e7e548000016c"

}

 

Check box elements include the id of each choice selected which can be matched up with data from the data.json file.

{

     elementType: "CheckBoxes",

     tourId: "5659862fa186afb063315e8f",

     elId: "56f0ab9f6772694eaf000025",

     viewerName: "Anonymous user",

     fingerprint: "PzJpy1Gdo7ei7ax9QohnotiJGsc=",

     checked[]: "56f0ab9f6772694eaf000026",

     checked[]: "56f0ab9f6772694eaf000027"

}

 

Drawn Response elements include the json data of the response. This can be used with a canvas library (e.g. fabric.js) to recreate the submitted image.

{

     elementType: "DrawnResponse"

     tourId: "5659862fa186afb063315e8f"

     elId: "56b8ddef6772696ec6000023"

     viewerName: "Anonymous user"

     fingerprint: "PzJpy1Gdo7ei7ax9QohnotiJGsc="

     drawingJSON: {"objects":[{"type":"path","originX":"center","originY":"center","left":285,"top":121.75,"width":238,"height":186,"fill":null,"stroke":"#FFFB00","strokeWidth":5,"strokeDashArray":null,"strokeLineCap":"round","strokeLineJoin":"round","strokeMiterLimit":10,"scaleX":1,"scaleY":1,"angle":0,"flipX":false,"flipY":false,"opacity":1,"shadow":null,"visible":true,"clipTo":null,"backgroundColor":"","path":[["M",168.5,151.5],["Q",168.5,151.5,169,151.5],["Q",169.5,151.5,168.75,151.5],["Q",168,151.5,163,151.5],["Q",158,151.5,150,151.5],["Q",142,151.5,131,151.5],["Q",120,151.5,107,151.5],["Q",94,151.5,80.5,150],["Q",67,148.5,55.5,144],["Q",44,139.5,33.5,130.5],["Q",23,121.5,17.5,115],["Q",12,108.5,8,102.5],["Q",4,96.5,2,90],["Q",0,83.5,0,80],["Q",0,76.5,0,72.5],["Q",0,68.5,1.5,63.5],["Q",3,58.5,7,53],["Q",11,47.5,16.5,41.5],["Q",22,35.5,28.5,30],["Q",35,24.5,44.5,18],["Q",54,11.5,63.5,8],["Q",73,4.5,86.5,2.5],["Q",100,0.5,114.5,0],["Q",129,-0.5,143.5,0],["Q",158,0.5,171.5,7.5],["Q",185,14.5,193.5,19.5],["Q",202,24.5,210,32.5],["Q",218,40.5,223.5,48],["Q",229,55.5,232.5,63],["Q",236,70.5,237,77],["Q",238,83.5,238,90],["Q",238,96.5,237.5,106.5],["Q",237,116.5,232,125],["Q",227,133.5,218,141.5],["Q",209,149.5,198.5,157],["Q",188,164.5,175.5,170.5],["Q",163,176.5,149,180.5],["Q",135,184.5,120.5,185.5],["Q",106,186.5,95,186.5],["Q",84,186.5,74.5,184.5],["Q",65,182.5,60.5,181],["Q",56,179.5,53.5,179],["Q",51,178.5,48,177.5],["Q",45,176.5,43.5,175.5],["Q",42,174.5,40.5,172.5],["Q",39,170.5,38.5,165],["Q",38,159.5,38,153.5],["Q",38,147.5,38,140.5],["Q",38,133.5,40.5,128],["Q",43,122.5,46,119],["Q",49,115.5,53,112],["L",57,108.5]],"pathOffset":{"x":0,"y":0}}],"background":"","scaleFrom":{"width":619,"height":348}}

     scaleFrom[width]: 619

     scaleFrom[height]: 348

     inTime :6.539367

}

 

Open response elements include the text inputted by the viewer.

{

     elementType: "TextResponse"

     tourId: "5659862fa186afb063315e8f"

     elId: "5671aafa677269395a000106"

     viewerName: "Anonymous user"

     fingerprint: "PzJpy1Gdo7ei7ax9QohnotiJGsc="

     text: "This is my answer"

}

 

Numerical response elements include the number inputted by the viewer.

{

     elementType: "NumResponse"

     tourId: "5659862fa186afb063315e8f"

     elId: "5671af3b6772693bbc000018"

     viewerName: "Anonymous user"

     fingerprint: "PzJpy1Gdo7ei7ax9QohnotiJGsc="

     number: 3

}


Discussion Comments

Discussion comments are a special case and have a comment property instead of an elementType. This will include the date the comment was posted, when in the video it was referencing and a way to identify the commenter.

{

     tourId: "5659862fa186afb063315e8f",

     elId: "56abfb9b6772695ae2000020",

     comment: {

           _id: "578539ec0b0a840d28000003".

acl: { read: [], write: [] },

tour: "5659862fa186afb063315e8f",

   element: "56abfb9b6772695ae2000020",

datePosted: :"2016-07-12T18:41:48.570Z",

inTime: 33.592622,

name: "Anonymous user",

user: 0,

replies: [],

checked : []

}








PHP example pseudo code:

 

 $elementType = $_POST["elementType"];

 if ($elementType == "NumResponse") {

   $tourId = $_POST["tourId"];

   $fingerprint = $_POST["fingerprint"];

   $answer = $_POST["number"];

   someDatabaseSaveFunction($tourId, $fingerprint, $answer);

} else if ...

 

Have more questions? Submit a request

Comments

Powered by Zendesk