Setup Guide: Getting Started with Vite Grader

Welcome to Vite Grader! This guide will walk you through the initial setup process using the setup wizard to get you up and running quickly and efficiently.

Prerequisites

Before you begin, ensure you have the following:

1. Canvas Account: Your teacher account credentials for Canvas.
2. Duolingo for Schools Account: Your teacher account for Duolingo for Schools.

Step 1: Getting Your API Tokens

Vite Grader needs API tokens to securely access your data on Canvas and Duolingo. These tokens allow Vite Grader to act on your behalf to fetch information and push grades. There are two main ways to obtain these tokens.

Method 1: Using the Vite Grader Bookmarklet (Recommended & Easiest)

Method 1: Using the Vite Grader Bookmarklet

This method uses a special browser bookmarklet—a small tool you add to your browser's bookmarks bar—to help you quickly and easily retrieve your API tokens from Canvas and Duolingo. The bookmarklet runs a script directly from the Vite Grader application to ensure it's always up-to-date and secure.

A. What is a Bookmarklet?

A bookmarklet is like a browser bookmark, but instead of taking you to a webpage, it runs a small piece of JavaScript code on the current page you're viewing. The "Vite Grader Token Helper" bookmarklet is specifically designed to:

• Simplify generating your Canvas API token.
• Quickly extract your Duolingo for Schools jwt_token.
• Automatically import these tokens for use in the Vite Grader setup wizard.

B. Installing the Vite Grader Token Helper Bookmarklet

To use this method, you first need to add the bookmarklet to your browser.

1. Ensure your Bookmarks Bar is visible:

   • Chrome: Go to View > Always Show Bookmarks Bar. (Or Ctrl+Shift+B / Cmd+Shift+B)
   • Firefox: Go to View > Toolbars > Bookmarks Toolbar. (Or right-click the toolbar area and ensure " Bookmarks Toolbar" is checked).
   • Edge: Go to Settings and more (...) > Settings > Appearance > Show favorites bar (select "Always").
   • Safari: Go to View > Show Favorites Bar.

2. Drag the following link to your Bookmarks Bar:

   Vite Grader Token Helper{const s=document.createElement('script');s.src='/public/bookmarklet.js?t='+Date.now() ;document.body.appendChild(s);})())

   Simply click and hold on the link above, then drag it onto your browser's bookmarks/favorites bar, and release.

C. Using the Bookmarklet to Get Your Canvas Token

1. Log in to your Canvas instance (e.g., isd271.instructure.com).
2. Once you are logged in and viewing any page within your Canvas instance, click the "Vite Grader Token Helper" bookmarklet that you added to your bookmarks bar.
3. The bookmarklet will activate and guide you. It is designed to:
   • Generate a new Access Token.
   • Pass it to the Vite Grader Setup Wizard page.

D. Using the Bookmarklet to Get Your Duolingo Token (JWT)

1. Log in to Duolingo for Schools with your teacher account.
2. Once you are logged in, click the "Vite Grader Token Helper" bookmarklet from your bookmarks bar.
3. The bookmarklet will automatically locate and read the jwt_token cookie that Duolingo for Schools uses for your session.
4. It will then automatically pass this token to the Vite Grader Setup Wizard page.

After using the bookmarklet for both services, you'll have your Canvas token and your Duolingo token ready for the setup wizard!

Method 2: Manually Getting Your API Tokens (Alternative)

Method 2: Manually Getting Your API Tokens

If you prefer, or if the bookmarklet method isn't suitable for your setup (for example, if you cannot run custom JavaScript on your institution's pages or if the bookmarklet encounters an issue), you can retrieve the tokens manually by following the steps below.

A. Getting Your Canvas Token

1. Log in to your Canvas instance (e.g., isd271.instructure.com).

2. In the left-hand global navigation menu, click on Account, then Settings.

3. Scroll down to the Approved Integrations section.

4. Click the + New Access Token button.

5. For Purpose, you can enter something descriptive like "Vite Grader App".

6. For Expires (optional), you can set an expiration date if you wish. For long-term use, you might leave this blank, but be aware of your institution's policies.

7. Click Generate Token.

8. Important: Canvas will show you the token only once. Copy this token immediately and store it in a safe place (like a password manager). You will need it for the Vite Grader setup wizard.

   (Ideally, replace this placeholder with an actual screenshot or GIF)

B. Getting Your Duolingo Token (JWT)

The Duolingo token is a jwt_token that your browser uses when you are logged into Duolingo for Schools.

1. Log in to Duolingo for Schools.

2. Open your browser's Developer Tools:

   • Chrome/Edge: Right-click anywhere on the page, select "Inspect", then go to the "Application" (or "Storage" in older versions) tab.
   • Firefox: Right-click, select "Inspect Element", then go to the "Storage" tab.

3. In the Developer Tools, look for "Cookies" in the left-hand panel and select the cookie for https://schools.duolingo.com/.

4. Find the cookie named jwt_token.

5. Copy the entire value of this jwt_token. This is your Duolingo token. Store it securely for the setup wizard.

   (Ideally, replace this placeholder with an actual screenshot or GIF)

   Note: This token might expire or become invalid if you log out of Duolingo or clear your browser cookies. You may need to repeat this step periodically if Vite Grader loses connection to Duolingo.

Step 2: Using the Setup Wizard

Once you have your Canvas and Duolingo tokens, you're ready to start the Vite Grader setup. The setup wizard will guide you through all necessary initial configuration steps in the correct order.

1. Navigate to the Vite Grader application URL.

2. If it's your first time or if the system detects no prior setup, you should be automatically directed to the Setup Wizard (located at /setup).

3. The wizard will guide you through the following steps:

   • Connect to Services:

     • You'll be prompted to enter your Canvas Token and Duolingo Token that you obtained in Step 1.
     • Vite Grader will verify these tokens to establish a connection.

   • Match Canvas Courses with Duolingo Classrooms:

     • The wizard will help you link your Canvas courses to your Duolingo classrooms.
     • For each pair, you will set an XP Goal. This is the Duolingo XP a student needs in a grading period to achieve the "Max Base Grade."

   • Match Students:

     • For each matched course-classroom pair, the wizard will guide you to match your Canvas students with their corresponding Duolingo accounts. This ensures XP is correctly attributed.

   • Configure Grading Periods:

     • Define your current main academic term (e.g., Trimester, Semester) by selecting its start and end dates.
     • Within this main term, add individual grading periods (e.g., "Week 1," "Unit 1"). For each, you'll specify a name, start date, and end date. These periods determine the date ranges for fetching Duolingo XP.

       Assignment Names

       Vite Grader will automatically use the names of the grading periods you set up to decide the corresponding assignment names in Canvas.
       Period 1 → Duolingo 1, Period 2 → Duolingo 2, etc.

   • Set Basic Grading Settings:

     • The wizard may ask you to review or set key grading parameters:
       • Max Base Grade: The maximum points for meeting the XP goal (e.g., 20 points).
       • Max Extra Credit Grade: Maximum extra credit points (e.g., 10 points).
       • Bonus Points: Enable and set points for "Running Bonus" and "Period Bonus."
     • You can usually adjust these later in the main Settings page.

4. Follow all instructions within the setup wizard carefully. It's designed to ensure all foundational elements are configured correctly.

After the Wizard

Once you complete the setup wizard:

• Your core settings, grading periods, course matches, and student matches should be configured.
• You can always revisit individual sections like Settings, Grading Periods, Courses, or Students from the main navigation if you need to make adjustments or add new items later (e.g., a new grading period or a new student).

You are now ready for day-to-day use of Vite Grader! Proceed to the Normal Usage Guide.