Introduction

Picmonic uses the industry standard Learning Tools Interoperability™ 1.1 specification to allow Picmonics to be launched from from a remote server on behalf of a User.

View more information about the LTI 1.1 specification.

Launch Request

Basic PHP launch form. Make sure you replace "YOUR_CONSUMER_KEY" AND "YOUR_CONSUMER_SECRET" with your own credentials.

<?php
//
// Configuration
//
$key = "YOUR_CONSUMER_KEY"; // update with your provided consumer key
$secret = "YOUR_CONSUMER_SECRET"; // update with your provided consumer secret
$launch_data = [
    "picmonic_id" => "2594", // the id of the picmonic you want to launch (requires one of picmonic_id|track_id|pathway_id)
    "track_id" => "242", // the id of the picmonic you want to launch (requires one of picmonic_id|track_id|pathway_id)
    "pathway_id" => "176", // the id of the picmonic you want to launch (requires one of picmonic_id|track_id|pathway_id)
    "resource_link_id" => "120988f929-274612", // a unique id generated for each placement of the picmonic in your LMS (required)
    "context_id" => "2594", //a unique id generated for the context in your LMS (i.e. course being launched from)  (required)
    "user_id" => "292832126", // user's id from your system (required)
    "lis_person_name_given" => "John", // user's first name (optional)
    "lis_person_name_family" => "Snow", // users's last name (optional)
    "lis_person_contact_email_primary" => "john.snow@lmsng.school.edu", // user's email (optional)
    "lis_result_sourcedid" => "11296002", // a unique indentifier you send us for each launch request. we will send it back along with the quiz results when a user finishes a quiz (required)
    "lis_outcome_service_url" => "https://your-domain.edu/outcomes", // your url which we will send the results of the quiz to. See Outcomes for more information. (required)
    "context_label" => "picmonic", // must be "picmonic" (required)
    "roles" => "Learner", // must be "Learner" (required)
    "basiclti_submit" => "Launch Picmonic", // make sure if a button is used as part of the form to include it in the data to be signed
];

$launch_url = "https://www.picmonic.com/login/lti";

// Basic LTI uses OAuth to sign requests
// OAuth Core 1.0 spec: http://oauth.net/core/1.0/
$now = new DateTime();
$launch_data["lti_message_type"] = "basic-lti-launch-request";
$launch_data["lti_version"] = "LTI-1p0";
$launch_data["oauth_version"] = "1.0";
$launch_data["oauth_signature_method"] = "HMAC-SHA1";
$launch_data["oauth_consumer_key"] = $key;
$launch_data["oauth_timestamp"] = $now->getTimestamp();
$launch_data["oauth_nonce"] = uniqid('', true);
$launch_data["oauth_callback"] = "about:blank";

// In OAuth, request parameters must be sorted by name
$launch_data_keys = array_keys($launch_data);
sort($launch_data_keys);
$launch_params = [];
foreach ($launch_data_keys as $key) {
    array_push($launch_params, $key . "=" . rawurlencode($launch_data[$key]));
}
$base_string = "POST&" . urlencode($launch_url) . "&" . rawurlencode(implode("&", $launch_params));
$secret = urlencode($secret) . "&";
$signature = base64_encode(hash_hmac("sha1", $base_string, $secret, true));
?>

<html>
<head>
    <title>Basic Launch Request</title>
</head>
<body>
    <iframe width="854" height="480" frameborder="0" name="picmonic_iframe"></iframe>
    <form name="ltiLaunchForm" id="ltiLaunchForm" method="post" target="picmonic_iframe" encType="application/x-www-form-urlencoded" action="<?php echo$launch_url; ?>" >
        <?php foreach ($launch_data as $k => $v ) { ?>
            <input type="hidden" name="<?php echo $k ?>" value="<?php echo $v ?>">
        <?php } ?>
        <input type="hidden" name="oauth_signature" value="<?php echo $signature ?>">
        <input type="submit" name="basiclti_submit" value="<?php echo$launch_data['basiclti_submit']; ?>"/>
    </form>
<body>
</html>

A basic launch request is required to load a Picmonic or Quiz on several Picmonics.

We recommend loading the launch form inside an iframe with a width of 854 and height of 480.

Required Parameters

LTI Version Parameters

Field	Type	Length	Description
lti_message_type	string	255	Must be `basic-lti-launch-request`
lti_version	string	255	Must be `LTI-1p0`
context_id	string	255	TC's identifier for context for this launch link e.g. `436646`
context_label	string	255	Must be `picmonic`
resource_link_id	string	255	TC's unique identifier for this launch link. This is an opaque unique identifier that the TC guarantees will be unique within the TC for every placement of the link. e.g. `120988f929-274612`

Picmonic

*One and only one of the following parameters must be sent:

Field	Type	Length	Description
picmonic_id	integer	11	the id or slug of the Picmonic e.g. `2594`
track_id	integer	11	the id of the Track e.g. `242`
pathway_id	integer	11	the id of the Pathway e.g. `176`
app	integer	11	1 to open the full app instead of specific resource

User Data

Field	Type	Length	Description
user_id	string	255	TC's unique user identifier e.g. `292832126`
roles	string	255	Must be `Learner`

Outcomes

Field	Type	Length	Description
lis_result_sourcedid	string	2083	This field identifies a unique row and column within the TC gradebook. This value will be passed along with the outcomes to the `lis_outcome_service_url`. e.g. `11296002`
lis_outcome_service_url	string	2083	The URL for receiving the outcome after a user has completed a Quiz e.g. `https://your-domain.edu/outcomes`

OAuth

For more information about generating the required fields see the example code or visit the OAuth 1.0 Specification.

Field	Type	Description
oauth_version	string	Must be `1.0`
oauth_signature_method	string	Must be `HMAC-SHA1`
oauth_consumer_key	string	Company key given - e.g. `lmsng.school.edu`
oauth_timestamp	string	Current unix timestamp e.g. `11296002`
oauth_nonce	string	A nonce is a random string, uniquely generated for each request e.g. `224535671`
oauth_callback	string	Must be `about:blank`
oauth_signature	string	See the example code or visit the OAuth 1.0 Specification e.g. `TPFPK4u3NwmtLt0nDMP1G1zG30U=`

Optional Parameters

User Data

Field	Type	Length	Description
lis_person_name_given	string	255	Users's first name e.g. `John`
lis_person_name_family	string	255	Users' last name e.g. `Snow`
lis_person_contact_email_primary	string	255	Email address `john.snow@lmsng.school.edu`

Outcomes

replaceResult

An example JSON replaceResult request

{
  "lti_delivery_id": 18,
  "lis_result_sourcedid": "11296002",
  "correct": 2,
  "attempts": 7,
  "hints": 1,
  "score": 0.2857142857142857,
  "seat_time": 1158,
  "quiz_start_time": 1542155447,
  "quiz_end_time": 1542156505,
  "start_unix_timestamp": 1542155347,
  "end_unix_timestamp": 1542156505,
  "video_watched": true,
  "questions": [
    {
      "question_id": 56696,
      "question_text": "Which of the following genetic classifications is most likely associated with Niemann-Pick disease?",
      "correct_answer": "Autosomal Recessive",
      "explanation": "Niemann-Pick is inherited in an autosomal recessive modality. This means two copies of the abnormal gene must be present in order for the disease to develop.",
      "attempted": 1,
      "correct": 0,
      "hint": 0,
      "selected_answer": "Mitochondrial Inheritance",
      "start_time": 1542155358,
      "answer_time": 1542155361,
      "end_time": 1542155381,
      "total_time": 23
    },
    {
      "question_id": 56698,
      "question_text": "Niemann-Pick disease is more common in which of the following populations?",
      "correct_answer": "More Common in Ashkenazi Jewish Population",
      "explanation": "There is an increased disease prevalence in the Eastern European Ashkenazi Jewish population.",
      "attempted": 1,
      "correct": 1,
      "hint": 0,
      "selected_answer": "More Common in Ashkenazi Jewish Population",
      "start_time": 1542155381,
      "answer_time": 1542156037,
      "end_time": 1542156039,
      "total_time": 658
    },
    {
      "question_id": 56704,
      "question_text": "Which of the following is a histologic feature of Niemann-Pick disease?",
      "correct_answer": "Foam Cells",
      "explanation": "Foam cells are phagocytes that have accumulated large amounts of oxidized low-density lipoproteins. Numerous small vacuoles filled with lipids are created causing the cytoplasm to appear foamy.",
      "attempted": 1,
      "correct": 1,
      "hint": 1,
      "selected_answer": "Foam Cells",
      "start_time": 1542156039,
      "answer_time": 1542156050,
      "end_time": 1542156051,
      "total_time": 12
    },
    {
      "question_id": 56702,
      "question_text": "Niemann-Pick disease most likely results in which of the following?",
      "correct_answer": "Neurodegeneration",
      "explanation": "Neurodegeneration involves progressive deterioration of the central nervous system due to accumulation of sphingomyelin.",
      "attempted": 1,
      "correct": 0,
      "hint": 0,
      "selected_answer": "Hypoglycemia",
      "start_time": 1542156051,
      "answer_time": 1542156497,
      "end_time": 1542156497,
      "total_time": 446
    },
    {
      "question_id": 56697,
      "question_text": "Which enzyme deficiency is seen in Niemann-Pick disease?",
      "correct_answer": "Sphingomyelinase Deficiency",
      "explanation": "Sphingomyelinase, is deficient in this disorder, leading to an accumulation of sphingomyelin. This build up of sphingomyelin is attributed to the physiological symptoms seen in Niemann-Pick.",
      "attempted": 1,
      "correct": 0,
      "hint": 0,
      "selected_answer": "Arylsulfatase A Deficiency",
      "start_time": 1542156497,
      "answer_time": 1542156498,
      "end_time": 1542156499,
      "total_time": 2
    },
    {
      "question_id": 56700,
      "question_text": "Which of the following is a sign or symptom most likely associated with Niemann-Pick disease?",
      "correct_answer": "Cherry Red Spot on Macula",
      "explanation": "On fundoscopic examination, a small red spot is seen in the center of the macula of the retina. It is caused by accumulation of sphingomyelin in the retina and the relative transparency of the macula. Cherry red macula can be seen in several different lipid storage diseases.",
      "attempted": 1,
      "correct": 0,
      "hint": 0,
      "selected_answer": "Foamy Stools",
      "start_time": 1542156499,
      "answer_time": 1542156499,
      "end_time": 1542156500,
      "total_time": 1
    },
    {
      "question_id": 56701,
      "question_text": "Which of the following is a sign or symptom most likely associated with Niemann-Pick disease?",
      "correct_answer": "Hepatosplenomegaly",
      "explanation": "An accumulation of sphingomyelin in the liver and spleen causes enlargement of these organs at an early age.",
      "attempted": 1,
      "correct": 0,
      "hint": 0,
      "selected_answer": "Gout",
      "start_time": 1542156503,
      "answer_time": 1542156504,
      "end_time": 1542156504,
      "total_time": 1
    }
  ]
}

An example POX replaceResult request

<?xml version = "1.0" encoding = "UTF-8"?>
<imsx_POXEnvelopeRequest xmlns = "http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
  <imsx_POXHeader>
    <imsx_POXRequestHeaderInfo>
      <imsx_version>V1.0</imsx_version>
      <imsx_messageIdentifier>999999123</imsx_messageIdentifier>
    </imsx_POXRequestHeaderInfo>
  </imsx_POXHeader>
  <imsx_POXBody>
    <replaceResultRequest>
      <resultRecord>
        <sourcedGUID>
          <sourcedId>3124567</sourcedId>
        </sourcedGUID>
        <result>
          <resultCorrect>
            <language>en</language>
            <textString>23</textString>
          </resultCorrect>
          <resultAttempts>
            <language>en</language>
            <textString>25</textString>
          </resultAttempts>
          <resultHints>
            <language>en</language>
            <textString>0</textString>
          </resultHints>
          <resultScore>
            <language>en</language>
            <textString>0.92</textString>
          </resultScore>
          <resultSeatTime>
            <language>en</language>
            <textString>300</textString>
          </resultSeatTime>
          <resultStartUnixTimestamp>
            <language>en</language>
            <textString>1541011874</textString>
          </resultStartUnixTimestamp>
          <resultEndUnixTimestamp>
            <language>en</language>
            <textString>1541011892</textString>
          </resultEndUnixTimestamp>
        </result>
      </resultRecord>
    </replaceResultRequest>
  </imsx_POXBody>
</imsx_POXEnvelopeRequest>

After a quiz has been completed we will send a replaceResult request to the lis_outcome_service_url specified in the launch request with the lis_result_sourcedid for the resource_link_id.

Depending on the format for your account you will either receive a XML POX request or a JSON request.

The JSON format includes additional information about the questions answered.

It is the LMS responsibility to store and update the grade book accordingly.

JSON Request - Fields

Field	Type	Description
lti_delivery_id	integer	The unique delivery id number
lis_result_sourcedid	string	The provided lis_result_sourcedid
correct	integer	The total number of questions answered correctly
attempts	integer	The total number of questions attempted
hints	integer	The total number of hints used
score	decimal	The percentage of questions answered correctly in decimal form e.g. .75
seat_time	integer	Time user spent in seconds
quiz_start_time	integer	The unix timestamp of when the student started the quiz
quiz_end_time	integer	The unix timestamp of when the student finished the quiz
start_unix_timestamp	integer	The unix timestamp of when the launch request was sent
end_unix_timestamp	integer	The unix timestamp of when the student completed the session
video_watched	boolean	True if the student watched the educational audio for the Picmonic during the session
questions	array	A list of question objects

JSON Request - Question Object - Fields

Field	Type	Description
question_id	integer	The unique question id number
question_text	string	The question the user was asked
correct_answer	string	The correct answer
explanation	string	The explanation of the correct answer
attempted	integer	1 if the question was attempted 0 if not
hint	integer	1 if a hint was used 0 if not
selected_answer	string	The answer the use choose
start_time	integer	Unix timestamp of when the user started the question
answer_time	integer	Unix timestamp of when the user answered the question
end_time	integer	The Unix timestamp of when the user clicked next question
total_time	integer	Total time in seconds user spent on the question

POX Request Fields

Field	Type	Description
resultCorrect	integer	The total number of questions answered correctly
resultAttempts	integer	The total number of questions attempted
resultHints	integer	The total number of hints used
resultScore	decimal	The percentage of questions answered correctly in decimal form e.g. .75
resultSeatTime	integer	Time user spent in seconds
resultStartUnixTimestamp	integer	The Unix time of when the launch request was sent
resultEndUnixTimestamp	integer	The Unix timestamp of when the student completed the quiz

Errors

Error Code	Meaning
400	Invalid Request - Verify the required fields are being sent.
401	Unauthorized - Invalid signature. The generated oAuth signature for your request is invalid. Check your consumer key, consumer secret, and verify you are including all of the required data to be signed.
404	Not Found - The specified Picmonic Id could not be found. Verify you are sending the correct context_id.
500	Unknown Error - Please contact support if you encounter this error.

Support

For more information about how to get technical support, FAQs, and additional contact information visit our Picmonic LTI Support documentation.