Locations

Locations are how you declare which destinations in your app an instructor may place in their course. When an instructor adds your app, they pick one location; at launch time that location — its ID, type, label, and the params you configured — arrives in the launch's location claim.

Create one location per destination you want instructors to link to — e.g. a Chapter 3 Quiz location of type assessment with chapter=3.

Defining locations

Add and edit locations in Apps → your app → Settings → Locations (or via the management API). Each location has:

idstring

Assigned by Voshi when the location is created. This is how a launch names a location; store it in your app if you want to switch on it directly.

labelstring

A friendly name, shown in the dashboard and in the instructor's content picker, and used as the default name of the placement in the course.

typestringdefault: content

What the location is for:

Type	Meaning
assessment	Graded work. The only type that can pass a grade back. Placing it creates a gradebook line item and enables the grades API for its launches.
practice	Student practice; no grade attached.
content	Reading or reference material, no submission. The default.
setup	A configuration/setup screen, not a student-facing activity.

paramsobject

Zero or more static key-value pairs sent to your app on every launch of this location, e.g. chapter=3, mode=timed. Constraints:

• Up to 25 params per location.
• Names are identifiers: letters, numbers, and underscores, not starting with a number.
• Values are strings, up to 500 characters — and they arrive in the launch as strings ("3", never 3).

The default "Home" location

Every app has one default location ("Home"). It cannot be deleted, but you may change its label, type, and params. It is what a launch lands on if its placement names no location.

How instructors place locations (deep linking)

When an instructor adds content to their course, the LMS opens Voshi's content picker — your app is not involved. The picker shows your app with its locations; the instructor selects one, optionally renames the placement, and confirms. For assessment locations, a gradebook line item (starting at 100 points) is created at the same time.

Every launch of the placement carries the location's current configuration:

"location": {
  "id": "Il0c8n",
  "type": "assessment",
  "label": "Chapter 3 Quiz",
  "params": { "chapter": "3", "mode": "timed" }
}

Editing a location's label, type, or params applies immediately to content instructors have already placed.

warning

That same immediacy cuts the other way: deleting a location that instructors have placed breaks those placements — students clicking them will see a Voshi error page. Retire locations by relabeling or repurposing them rather than deleting, once your app is live.

Choosing a location strategy

Two workable patterns:

• One location per destination (Chapter 1 Quiz, Chapter 2 Quiz, ...) — the instructor's picker lists everything explicitly; your app switches on location.id.
• Few parameterized locations (Quiz with chapter=1, cloned per chapter) — fewer locations to maintain; your app switches on location.params.

Both arrive identically at launch time; pick whichever maps better to how instructors think about your content.