0. Introduction / Overview

App Developers should read the Admin, Teacher, and Student stories to see how the Quill process works:

Admin Story - Create Activities

Teacher Story - Assign Activities

Student Story - Complete Activities

This document outlines technical instructions for integrating the apps, and it assumes that the app developer already understands each of these components. Here is a brief review:

The three main ideas in the Quill platform are Apps, Activities, and ActivitySessions. Each app has activities. Each activity is a discrete learning goal; it typically takes 10 minutes to complete an activity, such as by asking the student to answer 15 questions. Each ActivitySession is a unique instance of an Activity. Each student has his or her own ActivitySessions.

Once an app developer adds his or her app to the platform, a Quill Admin creates an Activity on the app (Read the Admin User Story). A record of the activity is stored on both the Quill LMS and the app’s database. The ActivityID is the same value for both the Quill LMS and the app’s activity, linking the two together.

🚧

When developers enable Quill users to create activities, they must accept the ActivityID from the Quill LMS to associate the activity on Quill's end with the corresponding activity on the user's end.

When a teacher assigns an activity to a student it generates an ActivitySession. The ActivitySession contains the ActivityID. When the student presses “Start Lesson” the ActivitySession creates a link to the partner app that contains both the ActivityID and then ActivitySession ID. The partner app uses the ActivityID to load the appropriate Activity, and it uses the ActivitySession to track the student’s progress. When the activity is completed, the app developer posts data back to the Quill LMS using the ActivitySessionID to identify the data. This is a high level overview of the process.

1. Configuring Activities on 3rd party apps

Read the Admin Story
to see how activities are created from the user’s perspective.

The Quill Admin sets the form_url in the Quill LMS activity classification table. This URL corresponds to an endpoint on the 3rd party app that can configure the app-specific data about an activity. For example, http://myapp.com/form/. This endpoint receives a “uid” query parameter corresponding to the activity’s UID. For example, “http://myapp.com/form/?uid=XXX”.

That endpoint should load a configuration form for that 3rd party app. Developers should save that Activity UID along with additional configuration from the form itself. The Activity UID is used to associate the app’s activity with the corresponding instance on the Quill LMS.

How do you connect the LMS to an activity that already exists on an app?

You create an activity on the LMS, and then you select the activity on firebase that matches, and that creates an id.

2 . API Endpoint to Start Session

Read the Teacher’s Story to see how ActivitySessions are generated.

Read the Student’s Story to see how students consume ActivitySessions.

App should have an endpoint that can be accessed via the "Start Lesson" button on the LMS. That endpoint will receive a "student" query param that corresponds to the UID of the ActivitySession. It will also receive a “uid” query param corresponding to the UID of the activity. That endpoint can also receive an "anonymous" flag indicating an anonymous session.

👍

The URL Structure:

myapp.com/?student=XXX&uid=XXX (or ?anonymous=true)

Where the student and UID mean:

myapp.com/?student=[ActivitySessionUID]&uid=[ActivityUID]

Example:

grammar.quill.org/stories/module?student=1GmXxI871oyePgenBsf6JA&uid=E0COBlHa6wFi0fiSdmN8bg

Question: Where do I go to register my endpoint?

App developers provide the module URL and form URL to a Quill Admin. Contact Marcello at Marcello - at - quill - dot - org.

Question: How do I get the activity ID to match the app’s activity ID?

The activity ID needs to be the same ID as the module URL.

Question: How does the ActivitySession reference the gameplay session in the app?

App developers using firebase should key the gameplay session to the ActivitySession UID.

Module ID: - is this the same as activity ID? Is this the same as ActivitySessionID? Do apps have a ModuleSesionID?

3. Setting up the empirical-angular module

AngularFire apps should set up the empirical-angular module to pass data back to the Quill LMS. Include the 'empirical-angular' npm module. It defines a set of 3 services that help with LMS integration for angular apps: it exposes activity sessions, enables passing concept tag results, and provides a directive (HTML heading) for typing speeds.

Define the constant in your Angular constants:

empiricalBaseURL: https://staging.quill.org/api/v1

How to use the TypingSpeed directive:

<textarea type="text" class="form-control" typing-speed></textarea>

4. Starting Time

Every app must capture the time spent in the activity. The starting time section is under development.

App should mark the activity session as "started" when the user begins.

Other options:

• LMS marks started_at and app marks completed_at (setting of started_at needs to be implemented on LMS, completed_at is triggered as a before_save callback, and save is called upon reception of activity_session from LMS)
• app stores started_at and completed_at and only sends both fields when the activity is complete (suggestion) (note that this is not currently being done on Quill-Writer)

5. Concept Tag Results

Start here to learn more about concept tags.

Concept tags are a powerful system for capturing data about student performance. Essentially a concept tag is a bucket in which an app developer can input certain structured data and any unstructured data they'd like. This page only details how to integrate concept tags. Before you proceed, you should read this document that explains how concept tags work.

6. Finishing 3rd Party Activity

Once your application sends in concept tag results, and the student is finished, your app needs to inform the LMS. To achieve cross domain iframe communication, we are utilizing porthole.js. The quill.org environment provides a iframe proxy URL @ /porthole_proxy. This url should be used in your porthole.js configuration in your app.

To integrate in your application, be sure that you have the porthole.js client script on your module_url. The follow code snippet is all it takes to inform the LMS the student is finished with your activity.

  var windowProxy = new Porthole.WindowProxy('https://quill.org/porthole_proxy);
  var postObj = {
    action: 'activity_complete',
  };

  //If you have a student session, pass it in the postObj with the key id
  if ($state.params.student) {
    postObj.id = $state.params.student;
  }

  windowProxy.post(postObj);

Once the LMS receives your app's message, it will close your app and redirect the student to the results page of their activity session. If no student session is available, we simply redirect to the homepage. The anonymous flag is mainly for playing one off trial sessions of Quill applications, so this is sufficient.

Additional Details

• Keep in mind that anonymous sessions should not communicate back to the LMS, so the best thing to do is to guard all the above code with an "is anonymous session" status check.

• There's no way to create new concept tags and concept classes at the moment. If you need something that's not already in the Quill DB, talk to somebody.

// where does this go?

activity_path(activity, session: activity_session)

//becomes 

module_url/activities/activity.id?session=activity_session.id

Example Integration: Quill Grammar

Create a new Application

http://staging.quill.org/cms/activity_classifications

Create a new Activity Inside of the Application

http://staging.quill.org/cms/activity_type/quill-grammar-staging/activities

Select Add new Activity

When you click next, the cms manager will load the url you provided in Step 1.

I did a view source, and found this as the URL https://quillgrammarstaging.firebaseapp.com/activities/sentences/new/details?uid=IuMx8Yv-s-5_7KyONo4Uzg

Your app should use the provided uid. We believe that this will be the same uid that is passed to your module url when your particular activity is summoned.

You do whatever you need to. When you are done inside of your application’s iframe, go ahead and hit the save button on staging.quill.org.

Quill Grammar still needs to properly register the uid passed it.

Now we see https://quillgrammarstaging.firebaseapp.com/play/sw?anonymous=true&uid=IuMx8Yv-s-5_7KyONo4Uzg

Which has the same uid as the one we created!!

App Registration

Once an app has been built, it needs to be registered by an admin and given an OAuth key. Contact Quill maintainers to get that info.