Cordova ClassKit Plugin

Plugin to use Apple's ClassKit framework in your Cordova apps. Manage and create Contexts and Activities and add Activity Items to track the student's progress within the Schoolwork App.

• Prerequisites
• Supported Platform(s)
• Installation
• API
  • .initContextsFromXml(urlPrefix, success, error)
  • .addContext(urlPrefix, context, success, error)
  • .removeContexts(success, error)
  • .removeContext(identifierPath, success, error)
  • .beginActivity(identifierPath, asNew, success, error)
  • .endActivity(success, error)
  • .setProgressRange(fromStart, toEnd, success, error)
  • .setProgress(progress, success, error)
  • .setBinaryItem(binaryItem, success, error)
  • .setScoreItem(scoreItem, success, error)
  • .setQuantityItem(quantityItem, success, error)
• Add Contexts to your App
  • Static Contexts in XML File
  • Dynamic Contexts
• Deep Linking
• Contributing
• License

Prerequisites

Only works with Xcode 9.4 and iOS 11.4. Your Provisioning Profile must include the ClassKit capability. Read more about how to Request ClassKit Resources in this article. Also note that you can’t test ClassKit behavior in Simulator because Schoolwork isn’t available in that environment.

Supported Platform(s)

• iOS

Installation

1. cordova plugin add cordova-plugin-classkit
2. Turn on ClassKit in Xcode's Capabilities tab

The code is written in Swift and the Swift support plugin is configured as a dependency.

API

.initContextsFromXml(urlPrefix, success, error)

Init contexts defined in XML file CCK-contexts.xml

Parameters

Example

CordovaClassKit.initContextsFromXml(
  "myurlprefix://",
  () => {
    console.log('success');
  },
  e => {
    console.log("error:", e);
  }
);

CCK-contexts.xml (read Add Contexts to your App for more infos about the XML file)

<root>
    <context
        title="Parent Title 1"
        type="2"
        displayOrder="1"
        topic="math"
        identifierPath="parent_title_one">
        <context
            title="Child 1 1"
            type="3"
            identifierPath="parent_title_one, child_one"></context>
        <context
            title="Child 1 2"
            type="3"
            identifierPath="parent_title_one, child_two">
            <context
                title="Quiz 1 2 1"
                type="8"
                identifierPath="parent_title_one, child_two, child_two_quiz"></context>
        </context>
    </context>
    <context
        title="Parent Title 2"
        type="2"
        displayOrder="0"
        topic="computerScienceAndEngineering"
        identifierPath="parent_title_two">
        <context
            title="Child 2 1"
            type="3"
            identifierPath="parent_title_two, child_two">
            <context
                title="Quiz 2 1 1"
                type="8"
                identifierPath="parent_title_two, child_two, child_one_quiz"></context>
        </context>
    </context>
</root>

.addContext(urlPrefix, context, success, error)

Init context with identifier path

Parameters

All available context attributes:

All available type values (CLSContextType):

All available topic values (CLSContextTopic):

Example

var context = {
  identifierPath: ["parent_id", "child_id", "my_context_identifier"],
  title: "My Context Title",
  type: 2,
  topic: "math",
  displayOrder: 1
};
 
CordovaClassKit.addContext(
  "myurlprefix://", context,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.removeContexts(success, error)

Remove all contexts

Parameters

Example

CordovaClassKit.removeContexts(
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.removeContext(identifierPath, success, error)

Remove context with identifier path

Parameters

Example

CordovaClassKit.removeContext(
  ["parent_id", "child_id", "my_context_identifier"],
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.beginActivity(identifierPath, asNew, success, error)

Begin a new activity or restart an activity for a given context

Parameters

Example

CordovaClassKit.beginActivity(
  ["parent_id", "child_id", "my_context_identifier"], true,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.endActivity(success, error)

End the active activity

Parameters

Example

CordovaClassKit.endActivity(
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.setProgressRange(fromStart, toEnd, success, error)

Adds a progress range to the active given activity. developer.apple.com

Parameters

Example

CordovaClassKit.setProgressRange(
  0.0, 0.33,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.setProgress(progress, success, error)

Adds a progress to the active given activity. developer.apple.com

Parameters

Example

CordovaClassKit.setProgress(
  0.33,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.setBinaryItem(binaryItem, success, error)

Adds activity information that is true or false, pass or fail, yes or no.

Use an activity item of this type to indicate a binary condition, such as whether a student passed a test or failed it. Set the valueType property to specify how the binary condition should be reported to a teacher. developer.apple.com

Parameters

All available binaryItem attributes:

All available type values (CLSBinaryValueType):

Example

var binaryItem = {
  identifier: "binary_item_id",
  title: "My Binary Item 1",
  type: 0,
  isCorrect: true,
  isPrimaryActivityItem: false
};
 
CordovaClassKit.setBinaryItem(
  binaryItem,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.setScoreItem(scoreItem, success, error)

Adds activity information that signifies a score out of a possible maximum.

Use an activity item of this type to indicate the relative success in completing a task, like the number of correctly answered questions on a quiz. developer.apple.com

Parameters

All available scoreItem attributes:

Example

var scoreItem = {
  identifier: "total_score",
  title: "Total Score",
  score: 0.66,
  maxScore: 1.0,
  isPrimaryActivityItem: true
};
 
CordovaClassKit.setScoreItem(
  scoreItem,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.setQuantityItem(quantityItem, success, error)

Activity information that signifies a quantity.

Use an activity item of this type to associate a discrete value with a task. For example, you might use it to indicate how many times the user requested a hint while taking a quiz. developer.apple.com

Parameters

All available quantityItem attributes:

Example

var quantityItem = {
  identifier: "quantity_item_hints",
  title: "Hints",
  quantity: 8,
  isPrimaryActivityItem: false
};
 
CordovaClassKit.setQuantityItem(
  quantityItem,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

Add Contexts to your App

A context [...] represents an area within your app, such as a book chapter or a game level, that teachers can assign to students as tasks. You create a hierarchy of contexts to enable teachers to browse and assign your app’s content. You provide deep links to the content that the contexts represent to help teachers guide students to your content. developer.apple.com

There are two different types of contexts that you are able to initialize with this plugin: static (you know your contexts beforehand) and dynamic (you add contexts at run time).

Static Contexts in XML File

If you have a lot of static contexts you want to add to your app you could either call addContext(context, success, error) for every context or use a hierarchical XML representation of your contexts to initialize your contexts from calling initContextsFromXml(urlPrefix, success, error). Latter will be more clear and structured (at least for me... that's the reason I added this option... ;-) ). Therefore the plugin adds a CCK-contexts.xml file to your Resources folder in Xcode. The structure is as follows:

<root>
    <context identifierPath="parent_title_one"  title="Parent Title 1" type="2" displayOrder="1" topic="math">
        <context title="Child 1 1" type="3" identifierPath="parent_title_one, child_one"></context>
        <context title="Child 1 2" type="3" identifierPath="parent_title_one, child_two">
            <context title="Quiz 1 2 1" type="8" identifierPath="parent_title_one, child_two, child_two_quiz"></context>
        </context>
    </context>
    <context title="Parent Title 2" type="2" displayOrder="0" topic="computerScienceAndEngineering" identifierPath="parent_title_two">                
    ...
    </context>
    ...
</root>

You have to start with exactly one root node <root></root>. Now, nest all your <context></context> nodes in here building a hierarchical representation of all your static contexts. All available <context>-tag attributes are:

All available type values (CLSContextType):

All available topic values (CLSContextTopic):

Edit the CCK-contexts.xml file directly in the Resources folder in Xcode. Within your application call initContextsFromXml(urlPrefix, success, error) to init your contexts from CCK-contexts.xml.

Dynamic Contexts

To dynamically add contexts to your application use addContext(context, success, error).

Deep Linking

As Apple's documentation states you should/have to "provide deep links to the content that the contexts represent to help teachers guide students to your content". developer.apple.com The deep linking is not part of this plugin! Please use your 3rd party plugin of choice here, e.g. Ionic Deeplinks Plugin or Branch.

Contributing

This plugin needs testing!

1. Test it
2. Fork it
3. Create your feature branch (git checkout -b my-new-feature)
4. Commit your changes (git commit -am 'Add some feature')
5. Push to the branch (git push origin my-new-feature)
6. Create new Pull Request

License

This software is released under the [Apache 2.0 License][apache2_license].