Library Integration Guide

Overview

Clever’s goal is to support and empower great instructional technology companies. To that end, we are launching a Library where teachers can discover and adopt high-quality free and freemium-type products. Inclusion in the Library will highlight your product to the nearly 1.5 million U.S. K-12 teachers on Clever, and will allow those teachers to set up your product for their classrooms in a single click. The Library integration uses the open OAuth 2.0 authorization standard to perform single sign-on into your app.

What is the teacher experience?

When a teacher clicks on a new app in the Library, or via the ‘Sign Up with Clever’ button, the teacher is prompted with a consent screen to authorize Clever sharing their section (class) data with the app. Once authorized, Clever redirects the teacher to your app and you facilitate the OAuth Single Sign-On flow, using API calls to query for the user’s identity and classroom information. The teacher’s account is provisioned immediately, and the teacher is logged in to a free or freemium experience with their section and student data populated. The app is added to the Clever Portal for the teacher and their shared students, so those students can also log in to the app.

There are two entry points into your application that facilitate the teacher sign up process:

1. Teachers who find you through the Clever Library and click “Install".
2. Teachers who click “Sign Up with Clever” button on your website’s teacher signup page.

What data is shared?

If the teacher consents, your application will be authorized to access the following limited set of data fields for class information only belonging to that teacher. You'll use this data to automatically create user accounts and set up classes to make the signup experience as smooth and seamless as possible.

Teacher object data

• Clever ID - globally unique and stable ID for each user, created by Clever
• Name (first, middle, last)
• Email

Teacher’s shared sections, as primary or co-teacher

• Clever ID
• Name
• Section_number
• Teachers
• Students
• Subject (normalized to a set of possible values)*
• Grade (if available from the SIS)*

Student object data in those sections

• Clever ID (this is not sid_id or student_number; it’s a GUID generated by Clever)
• Name
• Grade (if available from the SIS)*

📘

*Normalized Fields

Clever normalizes certain fields to a defined set of possible values:

Subject: ["english/language arts","math","science","social studies","language","homeroom/advisory", "interventions/online learning","technology and engineering","PE and health","arts and music","other"]

Grade: [ "1", … ,"12", "PreKindergarten","Kindergarten","PostGraduate","Other"]

For more details on each field, and to see how the Library “teacher-shared” set of data fields compares with full rostering “district-shared” fields, please refer to Clever's Data Schema.

🚧

Why are school and district info not provided for Library users?

We don't share district or school ID in order to limit the data shared to what most districts consider a "non-PII" signup for students. This has been instrumental in getting districts excited about the Clever Library and promoting it to their teachers as a good way to sign up for new applications. About half of our current integrated apps do require school and/or district information, and in those cases, build in as part of the onboarding flow when a teacher first logs in this way a prompt for the teacher to pick their school.

Integration Requirements

To provide the best possible user experience, we ask that your integration supports the following:

Creating accounts on demand

1. As a teacher, when I log in the first time, provision my account immediately.
2. As a student who has been given access by my teacher, when I log in the first time, if I don’t have an account, provision my account immediately.

Syncing class data on first login
3. As a teacher, when I log in the first time, sync all my section and student info.

• If the section ID already exists in your system, this is likely a co-teacher; add the teacher to the existing section
• Your integration does not need to sync a classroom’s co-teachers (additional teachers who may also teach the class).

Ongoing syncing
4. As a teacher, I need a way to update my data on an ongoing basis.

• Option 1: Sync my data every time I log in.
• Option 2: Sync my data using a "Sync my Classes" button in the UI (when logged in).

In either case, resyncing of data should check for any new sections AND should check for updates to existing sections that have already been imported.

Technical Requirements
5. You must store and use Clever IDs as the primary identifier for all synced records.
6. Your redirect URI must be secured with https for production, and must not include a hash symbol (URI fragment) per the OAuth2 spec.
7. Add a "Sign Up with Clever" button to your website's registration or signup page.

Linking Existing Accounts (Optional)
8. As a teacher, when I first log in, ask me if I have an existing account. If so, prompt me to log in to my existing account and associate my Clever ID with my existing account
9. As a student, on my profile page, allow me to “Merge My Accounts” by logging in to my existing account and associating my Clever ID with my existing account

📘

If your application does not use classes (what Clever calls sections), you can skip requirements 3 and 4.

Next Steps

1. Check out a demo

Test drive the experience yourself by logging into https://clever.com/in/ssodemo using a demo teacher account: Skelly/CleverSSO, and clicking on “Library” at the top-right of the screen.

2. Set up your development app in Clever

See the Getting Started page for more details.

3. Build and test your integration

Using this guide, with additional support from Clever’s SSO developer documentation, build your OAuth 2.0 integration in a dev or staging environment. See Syncing Classes for details.

To test your integration, we’ve created a sandbox district that is intentionally not connected to your application in order to simulate a Clever teacher sign-up into your app. See Testing Your Integration for details.

4. Upload marketing collateral

For us to best showcase your product in the Library, please upload the following assets by completing the Marketing Collateral wizard in the new Library tab of your dashboard. You can do this prior to submitting for certification.

Here is a preview of what we ask for:

• App name
• Tagline - Describe your app in one short sentence. (60 char max)
• Long description - A full description of your app's capabilities and features.
• App icon
• PNG file format (no transparency)
• Dimensions - 400px by 400px
• Keep the corners of your icon square; our system will automatically apply evenly rounded corner.
• Think of this as the face of your app
• 10 MB size limit
• Feature banner
• PNG file format (no transparency)
• Dimensions - 400px wide by 240px high
• This should be different than your app icon
• Think of this as a poster for your app
• 10 MB size limit
• Screenshots - at least one and up to 5. Each screenshot may have an associated text description to go with it.
• PNG file format (no transparency)
• Dimensions - minimum 1200px wide by 800px high
• Screenshots should show the actual app in use and highlight a variety of features and capabilities
• 10 MB size limit for each
• Subjects
• Grade levels
• Device compatibility
• Pricing
• Legal information - link to privacy policy and terms of service

5. Sign data sharing agreement

Review and sign this standardized DSA that governs your relationship with the teachers who install your software through the Library and Sign Up with Clever and email a signed copy to [email protected].

6. Submit for certification to be included in the Library

Once you’ve tested your integration and meet all of the requirements, submit your integration by filling out this certification survey. We’ll then review your integration and send you a summary email. If all looks good, we’ll certify you as a launch partner and create a production app in Clever for you.