Tracking Content and Learning Activity

Percipio supports two methods for recording learner activity from external content platforms:

  • Track API – for non-xAPI-compliant systems using Skillsoft’s custom JSON schema.
  • Statements API – for xAPI-compliant providers using standard xAPI statements.

These APIs allow external providers to send user completion data, activity logs, and engagement status back to Percipio’s Learning Record Store (LRS), enabling unified reporting and learner progress tracking.

Track API (for Non-xAPI Providers)

Overview

The Track API allows external platforms that do not use xAPI to send learner activity events such as “started”, “in-progress”, or “completed” using a simplified, JSON-based schema. This helps Skillsoft unify learning records even from platforms that do not support standardized xAPI.

When to Use

Use the Track API when:

  • Your LMS or platform does not support xAPI.
  • You want to push learner progress and completion events to Percipio using a non-xAPI method.
  • You use custom metadata or identifiers instead of standard xAPI verbs.

Supported Use Cases

The following table lists some key use cases.

Scenario Description
Log a “started” event Learner begins a course in a partner platform; Percipio is updated for reporting.
Completion push Course marked “completed” in partner LMS → Percipio receives and logs completion.
Sync progress percentage Periodic updates of progress (e.g., 50% complete) pushed for active sessions.

API Description

Endpoints

http

POST /v1/partners/{partnerName}/track

POST /v1/partners/{partnerName}/organizations/{orgId}/track

Important: See “[Swagger Page URL]” for detailed API information.

Field-Level Examples

Below are examples of each field in the JSON schema:

Field Example (JSON) Description
content_id "content_id": "ext-101-cloud-basics" Unique identifier for the course being tracked, assigned by the content provider.
user "user": "john.doe@company.com" Email address, external user ID, or Percipio UUID.
status "status": "completed" Accepted values: started, in_progress, completed.
event_date "event_date": "2024-05-13T14:25:00Z" UTC timestamp of the event in ISO 8601 format.
completion_percentage "completion_percentage": 100 Progress as a percentage. Use 100 for completed.
duration_spent "duration_spent": 1200 Total seconds spent by the learner (e.g., 20 minutes = 1200).

Sample Payload

json

 

{

"content_id": "ext-101-cloud-basics",

"user": "john.doe@company.com",

"status": "completed",

"event_date": "2024-05-13T14:25:00Z",

"completion_percentage": 100,

"duration_spent": 1200

}

Authentication

OAuth2 (Client Credentials Grant Flow) is required. Use the same authentication process as described in the Authentication and Access section.

Integration Scenario

Scenario: A content provider sends a completion event when a learner finishes a course.

  1. Learner completes course on the content provider's platform.
  2. The content provider platform prepares JSON payload with status: completed, completion_percentage: 100.
  3. The platform calls the “/track endpoint” with an “OAuth2” token.
  4. Percipio stores event in the learner's record.

Troubleshooting and Error Codes

Code Meaning Resolution
400 Malformed JSON Check field types
401 Invalid token Refresh token, verify credentials
409 Duplicate event Track de-duplication logic
500 Server Error Retry or contact support

Best Practices

  • Validate user IDs against Percipio prior to submission.
  • Use the UTC time zone consistently.
  • Send events in order (e.g., “started” → “completed”).
  • Avoid duplicate event submissions to ensure clean reports.

Statements API (for xAPI-Compliant Providers)

Overview

The Statements API supports providers that follow the xAPI standard. It enables structured learner activity reporting using the canonical actor-verb-object format along with optional context and result metadata.

Percipio acts as an LRS (Learning Record Store) in this integration pattern.

When to Use

Use the Statements API when:

  • You already use xAPI to track learner activity.
  • Your platform sends activity using standard xAPI statements.
  • You want bidirectional sync: Percipio can also pull statements.

Supported Use Cases

Listed below are some key use cases:

Scenario Description
Push xAPI “completed” Learning partner sends a “completed” xAPI statement to Percipio.
Pull historical activity Percipio pulls prior statements from the partner’s endpoint for enrichment.

API Description

Endpoints

http

 

POST /v1/partners/{partnerName}/statements

GET /v1/partners/{partnerName}/statements

POST /v1/partners/{partnerName}/organizations/{orgId}/statements

Important: See https://api.percipio.com/content-aggregation/api-docs for detailed API information.

Statement Components and Samples

  • actor

    • json

     

    "actor":{

    "mbox": "mailto:john.doe@company.com",

    "name": "John Doe",

    "objectType": "Agent"

    }

  • verb

    json

     

    "verb": {

    "id": "http://adlnet.gov/expapi/verbs/completed",

    "display": { "en-US": "completed" }

    }

  • object

    • json

     

    "object": {

    "id": "https://yourprovider.com/courses/course-101",

    "definition": {

    "name": { "en-US": "Cloud Foundations" },

    "description": { "en-US": "Learn the basics of cloud computing." }

    },

    "objectType": "Activity"

    }

  • result (Optional)

    • json

     

    "result": {

    "completion": true,

    "success": true,

    "duration": "PT30M"

    }

  • context (Optional)

    • json

     

    "context": {

    "platform": "Your LMS",

    "instructor": {

    "name": "Jane Smith",

    "mbox": "mailto:jane.smith@yourlms.com"

    }

    }

Sample Statement

json

 

{

"actor": {

"mbox": "mailto:john.doe@company.com",

"name": "John Doe",

"objectType": "Agent"

},

 

"verb": {

"id": "http://adlnet.gov/expapi/verbs/completed",

"display": { "en-US": "completed" }

},

 

"object": {

"id": "https://yourprovider.com/courses/course-101",

"definition": {

"name": { "en-US": "Cloud Foundations" },

"description": { "en-US": "Learn the basics of cloud computing." }

},

"objectType": "Activity"

},

"result": {

"completion": true,

"success": true,

"duration": "PT30M"

},

"context": {

"platform": "YourLMS",

"instructor": {

"name": "Jane Smith",

"mbox": "mailto:jane.smith@yourlms.com"

}

}

}

Integration Scenario

Scenario: Federated partner pushes all completions via xAPI to Percipio daily.

  1. Partner prepares batched xAPI statements (with verb: “completed”).
  2. OAuth2 token is generated and POSTed to /statements.
  3. Percipio validates xAPI format and updates learner records.
  4. Partner receives HTTP 200 OK.

Authentication and Context

  • OAuth2 required (same method as other APIs).
  • xAPI statements should include X-Experience-API in the header.
  • Each statement must include the correct partner name in the endpoint URL.

Error Handling

Code Description Suggestion
207 Partial success Check response body for failed statements
400 Malformed xAPI Validate fields against xAPI
403 Unauthorized Token expired or invalid scope
500 Server error Retry or escalate to Skillsoft

Best Practices

  • Follow xAPI specifications strictly.
  • Test in the Development environment before implementing this API in the Production environment; validate against ADL's xAPI validator, if needed.
  • Keep statement size under or at 16 KB for optimal performance.
  • Use timestamps in UTC (event_time or timestamp).
  • Include meaningful result and context data for analytics.