V1 to V2 Migration Guide
Follow this guide if you are upgrading from version 1 of the server-side recording API.
Key changes
The V2 API introduces the following changes:
- TTL is no longer a valid option, you must use history for all requests.
- The API now supports GCP buckets for storage.
- The API has been redesigned to be more restful:
- Status complete files are now replaced with a callback server.
- SSR now requires the use of service accounts from a Unity Cloud organization.
- Deduplication has been removed as a feature. You will no longer see
409error codes for duplicate requests. - Auto end has been removed a feature. Requests will always run for the full duration of the history request.
- You no longer need to make a request to decode audio. Vivox will manage the state for you and the final product will be one .WAV file per speaker in the channel.
Authentication changes
SSR now requires the use of Unity Authentication for all requests.
- If you have not created an organization or project, create one. Refer to How to create a project for more information.
Once you have your project and organization you need to share the the details with your account manager. Your account manager will enable SSR for your organization.
Once SSR is enabled you need to create a service account to authenticate with the API. Refer to How to create a service account.
On the service account page, assign permissions to the service account. Select Manage organization permissions and assign the
Server Side Recording Processor Role. This enables this service account to access the SSR API.
To use this service account refer to How to authenticate with a service account.
API Changes
The full API documentation for SSR v2 is available in the Web Services API Docs.
This guide only covers what to change from the V1 API to the V2 API and does not include any new features. Refer to the full API documentation for an overview of new fields and options.
Request changes
The V2 API removes query parameters for passing request fields. All fields are now passed in the request body as JSON. The following is a list of fields that no longer exist.
destination_credentialsare now contained withinstorageOptions. To use AWS in the same way as the V1 API you need to replace a specific code segment.Replace this code With this code {
"destination_credentials": {
"bucket": "my-bucket",
"access_key_id": "secret",
"secret_access_key": "secret"
}
}{
"storageOptions": {
"provider": "aws",
"credentials": {
"bucket": "my-bucket",
"accessKeyId": "secret",
"secretAccessKey": "secret"
}
}
}Remove the
target_typefield. The V2 API only supports channel subscriptions.The
ttlfield has been removed. Use thehistoryfield to specify the duration of the recording.
Note: A new optional field callbackUri has been added. This field allows you to specify a callback server to receive a status of your job to a server you host. You can specify any URL in this field and Vivox make a request to it. Refer to the callback server documentation for more information.
SSR Decoder
The SSR decoder is no longer a separate request. The final product of the request will be one .WAV file per speaker in the channel and you can remove the tracking of job state from your infrastructure.
Callback server
With the removal of the status_complete and status_decoded, a mechanism was added to notify you when a job is complete. This is done through a callback server. Refer to the callback server documentation for more information.
This feature is completely optional, but it is the only way to know when a job is complete or why your audio is missing.