Site Scripts API Reference

Requirements:

• This feature assumes that you are a Thinkific Partner with access to the Partner Portal already. See Becoming An App Partner
• Site Script API requires Public apps that leverage OAuth to work

In this article

• What is the Site Scripts API?
• How Does it Work?
• How to use the Site Scripts API
• Key Considerations for Creating Site Scripts using the API
• Creator’s experience

What is the Site Scripts API?

Site Scripts API will help create a smoother app installation experience by automatically injecting Site Scripts into a Creator's site without the need of using Site Footer Code.

Instead of copying and pasting code into the Site Footer Code section, creators simply need to authorize the permission to inject scripts into specific pages. This saves creators time and frustration, especially if they are not comfortable with handling code.

This will translate into more successfully installed apps and faster realization of value for your apps.

How Does it Work?

You can learn more about this API and find schema and example use cases here.

How to use the Site Scripts API

OAuth Scope

Make sure the OAuth includes scope=write:site_scripts.

Example:

https://{subdomain}.thinkific.com/oauth2/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_mode=query&response_type=code&state={state}&code_challenge={code_challenge}&code_challenge_method={code_challenge_method}&scope=write:site_scripts

Using src and content

When using src, the top-level domain of the URL must match your App URL that is set in the Partner Portal. 

Example: An app with the url https://www.thinkific.com can have site scripts hosted on https://cdn.thinkific.com/path/to/script.js or https://www.thinkific.com/path/to/script.js or https://any.subdomain.thinkific.com/path/to/script.js

When using content, a header called HMAC-SHA265-SIGNATURE must be included in the request. The signature should be generated using your App's client secret and the value of the Site Script's content.

Ruby example

OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), APP_SECRET, site_script_content)

Key Considerations for Creating Site Scripts using the API

1. When to use content vs src?
   • When you use content, the content of your script will live on Thinkific. This value will be inserted into a <script> tag. This option is best for scripts that involve custom values (ie. configuration for a Course Creator).
   • Use src if you have your scripts hosted somewhere. This value will be used as the src attribute for a <script> tag.
2. What name and description should I give my scripts?
   • The name and description of your scripts will be shown to Creators who installed your app. They can see them (but not remove or modify them) under the App Settings Page.
3. Page Scopes
   • These are the pages that your scripts will run on. If you have pages that are not listed here that are critical to your app, please let us know - we would love to hear your ideas.
   • Your Page Scopes can include either a Page Group and/or each of the individual pages within these groups. See the "Schema" tab of the Site Scripts API documentation for details.
   • Using all Page Scopes can potentially impact the performance of the page for users. Unless it's necessary for your App's Site Scripts to render on all pages, we recommend limiting your Page Scopes to just the pages you need scripts to run.
4. Which location should I inject my scripts into?
   • If you need your scripts to run before the main body of HMTL is loaded, head is the right place; otherwise, footer is the default option
5. Which category should I pick for my script?
   • Functional: scripts that modify the UI for students to enhance their user experience
   • Analytics: lets Creators understand how students behave on their school’s site and in their courses (e.g. which pages they visit), to provide statistics on how their students interact with their site and courses, improve their school’s site and courses by identifying any errors, and performance issues
   • Marketing: lets Creators collect information to help market their courses, such as data on the impact of marketing campaigns, re-targeted advertising, etc
   • If your script falls under multiple categories, choose the one further down on the above list.
6. Writing your scripts
   • Be sure to scope any constants or variables to something unique, like your App name, to avoid any conflicts with Site Scripts from other Apps
   • If your Site Script manipulates the UI of a Creator's school, use DOM callbacks (ie. DOMContentLoaded) where necessary to guarantee that your script will execute when expected. The exception to this is Course Player, which is a single-page application that does not dispatch any DOM events.

Creator’s experience

When installing an app using Site Scripts API and with OAuth Scope with the write:site_scripts scope, the installation page will show Creators that your app is requesting Site Scripts access on certain pages.

After Site Scripts have been injected by the API, creators can see the name, description and page location(s) of the Site Scripts associated with the app under their App Settings Page.

To learn more about the creators’ experience with Site Scripts API, check out our Thinkific Apps and Integrations article.