We sometimes have customers in a situation where they want to pass along some custom url parameter to the course content when it's launched in Engine. It might be that the content can get passed a language code to affect what it uses by default. Or maybe the course is going to print a certificate, and you need to give a course code to use.
Whatever the use-case, it is possible with Engine to configure it so that a custom parameter added to the launch url will get passed along to the content as well. It works like this:
Step 1: Get your custom key/value pair on Engine's launch url
There are two ways that you can get your custom parameters onto Engine's launch url.
The best way to do this is to modify your BuildRegistrationLaunchLink request to include the parameters in the 'additionalValues' property of the launchLinkRequestSchema. So, you might end up with a payload for the API call that looks something like this:
Alternatively, you could add your extra parameters to the end of the url returned from the API. So, for example, if your call to BuildRegistrationLaunchLink returns something like
and then you could just append to that to have
Step 2: Configure Engine to recognize and use your custom parameter
There is a setting named SupplementalQueryStringParametersForAllActivities in Engine. The value of this should be a comma-separated list of url parameter names that you want Engine to pull off of the launch url and send to the course content page.
So, with our examples above, you'd configure this setting to have a value of: "myparam1, myparam2".
You can configure the value of this setting at any level through the API, so it could be something you set to apply to all launches, or just for specific courses that need them.
Step 3: Make sure the content can retrieve the parameter from the url
Once you have it configured and included on the launch url, Engine will add these parameters to the first page of the content that we launch to. This means, for example, the page we launch to in the content might now have a url like this:
You can verify this is working by opening the browser dev tools and looking at the Network tab to see that the parameters are showing on the url to the first page of the content.
It's important to note that Engine can only do this for the first page of the content. Since everything loaded by the course after that is under its control, the course itself will be responsible for retrieving and using those parameters on any subsequent resource requests, if needed.
Using this functionality is not something that comes up a lot, but it is a useful tool for situations where you really need to pass some value to the course.