Summary
The Extensions Configuration Service will allow developers to persist configuration information for their extension and expose it to their frontend and backend. Today, developers must implement this themselves to deliver a customized extension experience. This service alleviates the need to implement and pay the cost for this functionality.
Motivation
We recognize that the process to build an extension can be improved greatly. Even simple extensions that leverage a configuration variable require a backend for persistence. Extension backends can be challenging to build, expensive to host, and difficult to operate at large scale. Depending on an extension’s design, it may be subject to extremely large traffic spikes as viewers tune in to popular channels going live.
The Configuration Service is the first in a series of services designed to replace functionality commonly implemented by developers with Twitch hosted solutions. As additional hosted services become available, developing and operating extension backends will become easier. Our goal is to have developers focus on building a great user experience rather than implementation details.
Detailed Design
Defining Configuration
There are two configuration scopes: channel specific and extension-wide. Channel specific configuration is further split by write access into a segment only the developer can update (for use by an extension backend service (EBS)), and a segment for both the developer and broadcaster (intended for the config and live dashboard pages to update directly).
Setting Configuration
Developers have control over configuration. To set broadcaster configuration, there is the Twitch.ext.configuration.set() function in the JavaScript helper API. This method will reject viewers or moderators; it should only be invoked from the config or live dashboard views.
The following API is available for extensions backends to set configuration:
PUT https://api.twitch.tv/extensions/<extension_id>/configuration
{
“segment”: “developer|broadcaster|global”,
“channel”: <channel_id>
“version”: <config_version_name>
“content”: <data_string (e.g. escaped json or base64 encoded binary)>
}
The PUT request requires a signed JWT (external or broadcaster roles are allowed). The channel element is ignored when the segment type is global; it does not need to be sent for this case. The version field should match the required version specified in the dev site, and will be used to verify that broadcasters are ready to activate after saving configuration. The remainder of the body is the configuration payload to be updated. Developers are responsible for the serialisation format of the content.
Retrieving Configuration
Configuration is made available to Extension frontends when they load. It is accessed by the Twitch.ext.configuration.onChange() callback registration function in the JavaScript helper API.
If required, Extension backends can retrieve configuration by calling:
GET https://api.twitch.tv/extensions/<extension id>/configuration
Size Limits
- 5KB for each per-channel broadcaster segment
- 5KB for each per-channel developer segment
- 5KB for the per-extension global segment
Rate Limits
Configuration updates are limited to ten calls per segment per minute.
Dev Site Updates
Today, the dev site contains a “Required Configurations” field that may be used by developers to confirm necessary configuration before activation. A “Configuration Location” drop down will be introduced above this field with the three options, “Twitch hosted”, “Custom”, and “None”, allowing developers to select an extension’s source of configuration. “Required Configurations” will be renamed to “Configuration Version” and only appears when “Configuration Location” is not “None”.
Developer Rig Updates
The Developer Rig will be updated to allow local development of an extension using configuration service capabilities before the service is made available.
Additionally, the Developer Rig will provide an interface to retrieve and update extension configuration.
Rollout Considerations
The configuration service is not mandatory for extensions. Any developer can choose to leverage the configuration service for their extension by updating the configuration settings on the dev site.
Prior to making the configuration service available to developers, Twitch will add support for it in the Developer Rig. This will allow developers to locally test what it is like to leverage the configuration service once it is live.
When migrating existing extensions to use the configuration service, developers should preload existing configuration into the service before releasing the updated extension.
Drawbacks
Functionality provided by the configuration service will expand over time. The following areas will have future design and development efforts:
- Live delivery of configuration updates: two defining features of configuration are that it is long-lived and changes infrequently. There is often urgency to propagate changes immediately to currently active clients for both extension frontends and backends. In the initial rollout of the configuration service, updates will require a reload. Backends that require live configuration updates should remain the source of truth of configuration.
- Configuration schema updates: developers will initially be responsible for all configuration schema updates and migrations.
-
The configuration service is not a state service: attempting to use the configuration service to distribute continually updating state will cause rate limits to be triggered and subsequent requests to be discarded.
Storage limits: decisions around initial storage limits were made based upon a number of different inputs. This may be revisited in the future as additional use cases appear.
Alternatives
There have been many internal discussions around what the configuration service is, or even should be. A delineation was drawn between configuration and state, where configuration represents long-lived data and state was transient. As conversations continued, it became clear that state and configuration have different requirements. Persisting configuration sees much more use in current extensions than persisting and passing state.
This new service is optional. If more custom configuration options are necessary for their use case, a developer may choose to implement something tailored.