Clever Developer Docs

Driving Student Engagement with Goals

Integrate with Clever Goals to improve student engagement with your application. Sharing data with Goals will align teachers, school leaders, and district leaders around your best implementation practices.

Overview

What is Goals?

Clever Goals is a new product, purchased by districts to increase student engagement with learning software. Applications share minutes and learning progress data with Clever Goals via the Goals API. Clever Goals delivers that data to users across the school district to help every student use software effectively.

Rather than replace application dashboards and reports, Clever Goals seeks to highlight the “headline” metrics, and drive district users to application dashboards for deep dives into how software is being used.

Why integrate with Goals?

Goals offers several benefits to applications:

  • Drive student engagement in your product -- students in pilot schools with Goals use their software 24% more on average, as compared to students in schools without Goals

  • Direct traffic to your application’s metrics page through links in the Goals dashboard

  • Lead the conversation between district admins, teachers, and parents about software usage by creating consistent metrics and views

  • Highlight the data most relevant to your software so teachers and students get the value you intend out of your program

How does it work?

  1. Define your app’s progress metric and set recommended minutes/progress goals.
  2. Students use your application
  3. At least once a day, send minutes and progress metrics to Clever via the Goals API
  4. Clever aggregates and formats the data
  5. Students view their own progress in the Clever Portal, and teachers and administrators see insights into key metrics which also deep link into your application's internal reporting tools

For more information about the district experience, see the Goals Product page.

Choosing your key metrics

There are two types of metrics you'll send to Clever: minutes and a progress metric. Both metrics should be cumulative totals for the school year for a given student.

1. Minutes

Active, cumulative minutes spent in your application since the beginning of the school year, updated at least daily

Examples

  • 15 minutes
  • 32.5 minutes

Best practices

  • Only count "active" minutes, i.e. when the student is engaged in a lesson. Don't count inactive or idle minutes, when the user is on a non-curricular page, after a set timeout (no mouse or keyboard input for X minutes), or if the user switches browser tabs.

2. Progress metric

Cumulative units of learning completed in your application for the year, updated at least once daily

Examples

  • 2 lessons/activities/quizzes completed
  • 3 books read
  • 4.2 standards mastered
  • 5.8 modules finished

What makes a good progress metric?

  • Easy to understand. There are a lot of stakeholders for the reports - students, teachers, principals, district admins - don't assume they'll all be experts in the application

  • Changes on a daily if not weekly basis. If it takes a month to complete a unit, "units completed" will be a poor progress metric

  • Represents thoughtful, intentional work. "Quizzes passed" is a better metric than "Quizzes attempted" - so arbitrary clicking doesn't appear as progress

  • Measures completion - increases monotonically. A good progress metric is analogous to "pages read" in a book, not "current page" or "reading speed"

Cumulative data should only increase in value; this helps us build more opinionated reports that can identify when a student is "stuck." If there are scenarios in your application where cumulative minutes or progress may decrease, please let us know.

Now that you understand the metrics involved, it's time to learn how to use the Goals API to send Clever these metrics.

Using the Goals API

To integrate with Goals, you need to build an automated sync that sends your metrics dataset for all active students, on a per-district basis, to Clever using the Goals API at regular intervals.

Let's break this down:

  • All active students: All students who have active accounts in your application (i.e. not archived or inactive)

  • Per-district basis: Each dataset and corresponding API request should be scoped to the district level, since you'll be using district-app bearer tokens to authorize your API requests. So if your app is connected to 3 districts, you'll send 3 sets of student data using 3 requests with corresponding tokens (one request for each district).

  • Regular intervals: At least once every 24 hours, but ideally more frequently than that. For instance, some of our partners sync data every hour.

Note that sending Goals data is idempotent, meaning multiple identical API requests will have the same effect as a single request. So, you can retry requests if necessary and the result will be the same.

Clever accepts two data in either JSON format (preferred) or CSV.

Requests using JSON

For each district in your database using Goals, construct a POST request like so:

POST https://api.clever.com/v2.0/metrics
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
  "data": {
    "students": [
      {
        "clever_id": "4fd43cc56d11340000000005",
        "metrics": {
          "minutes": 126,  // Must be minutes
          "lessons_completed": 23 // Can be any form of noun_verb
        }
      },
      ...
    ]
  }
}

In place of YOUR_ACCESS_TOKEN, provide your application's private district-app bearer token (available from your application dashboard or from querying /oauth/tokens).

You'll then provide parameters as JSON within the body of the request. Within data, you'll include an array of students objects for all active district students, each of which includes the following name/value pairs:

Field Name
Format
Description

clever_id

String

The unique Clever ID for the student.

metrics

Object

The metrics object contains the student's cumulative minutes and progress data.

While the key name for the minutes metric must be minutes, the key name for your progress metric is up to you to decide. We ask that you format this as nouns_verbed such as lessons_completed or modules_finished.

Requests using CSV files

For each district in your database using Goals, create a CSV file with a row for every student:

File Headers: clever_id, minutes, lessons_completed
File Format: Comma Separated Value (CSV)

Responses

The Goals API uses HTTP status codes to indicate the status of your requests. We adhere to the status and error code standards of Clever's Data API.

Frequently asked questions

Q: Do we need to send the entire district's data at once? Can I upload students on a per-school basis instead?
A: Strive to update all active students within a district at once. If necessary, you may upload multiple subsets of students within the district, e.g. by school or by class. Clever will update data for students we receive.

Q: Can applications view the goals districts set in the Goals product?
A: During the Goals onboarding process, you can share recommended minutes and progress targets for your application. These goals can be adjusted at the district, school, or student level. Contact us if you’re interested in seeing data on how goals for your application are being set.

Q: What if I don't have cumulative data from the start of the school year?
A: If this data is unavailable, don't guess; we recommend simply starting at zero from where you are.

If you have any questions about what metrics to use or how to build your integration, please reach out to us, we want to help!


What's Next

Submit your integration for Goals Certification!

Goals Certification

Driving Student Engagement with Goals