Local screenshot upload

This page shows you how to enable screenshot uploads on your app and handle screenshot upload callbacks.

Understand the tech

When you enable screenshot upload, you set the interval between screenshots. After each interval, RTC SDK takes a screenshot of the video stream sent by local users, and uploads the image to Agora SDRTN®. Agora SDRTN® uploads each screenshot to your third-party cloud storage and sends a callback notification to your server in the form of an HTTPS request.

Screenshot upload

Prerequisites

Before implementing the Agora local screenshot upload feature, take the following steps:

1. Activate local screenshot upload service

   In Agora Console, select RTC Services from the sidebar, then locate the Video Screenshot Upload card and turn on its toggle. Select the settings icon on the card to open its configuration panel.

   

2. Configure third-party cloud storage

   Select the settings icon on the Video Screenshot Upload card to open its configuration panel.

   

   Once you turn on Enable Video Screenshot Upload, you can't disable it.

   Currently, the Agora local screenshot upload service only supports Amazon S3 as the third-party cloud storage provider. If you want to use a different provider, contact technical support.

   Fill in the following information:

   • Storage: The third-party cloud storage provider. Fixed to AWS.

   • Callback URL: The server address to receive callback notifications of local screenshot upload results.

   • Endpoint: Specify the access domain (Endpoint) of the bucket. See AWS Official Documentation for details.

   • Region: The data center region setting for third-party cloud storage. See AWS Official Documentation for details.

   • Access key: String type, the access key of the third-party cloud storage. Best practice is to provide a write-only access key.

   • Secret key: String type, the secret key of the third-party cloud storage.

   • Bucket Name: String type, the bucket name of the third-party cloud storage. The bucket name must comply with the naming rules of the corresponding third-party cloud storage service.

   • Filename Prefix: (Optional) JSON Array, an array composed of multiple strings, indicating the storage location of screenshots in the third-party cloud storage. For example, if fileNamePrefix = ["directory1","directory2"], the prefix directory1/directory2/ will be added to the screenshot filename, that is, directory1/directory2/xxx.jpg. The prefix length, including slashes, must not exceed 128 characters. The string should not contain symbols such as slashes, underscores, parentheses, and so on. The supported character set is as follows:

     • 26 lowercase English letters a-z
     • 26 uppercase English letters A-Z
     • 10 digits 0-9

   Sample configuration

   • Storage: AWS
   • Callback URL: https://webhook.site/2e75da2d-xxxx-xxxx-xxx-a0ef44a5259d
   • Endpoint: s3.cn-north-1.amazonaws.com.cn
   • Region: cn-north-1
   • Access key: 12345678
   • Secret key: abcd123
   • Bucket Name: test-artifacts
   • Filename Prefix: test

3. Integrate RTC SDK

   Integrate the RTC SDK (including the local screenshot upload dynamic library) into your project, join a channel, and publish a video stream. See SDK quickstart for details.

Implement local screenshot upload

You enable screenshot upload in your Video Calling client and handle the notification callback from Agora on your callback server.

Enable screenshot upload

Call the enableContentInspect method to enable the local screenshot upload feature. After successfully enabling the feature, the SDK will capture screenshots at the specified frequency and upload them to the Agora cloud server. To implement this logic, refer to the following code:

const inspectConfig = {
  // Set the interval for local screenshot to 2000 milliseconds (2 seconds), with a minimum value of 1000.
  interval: 2000,
  // (Optional) Set the address prefix for third-party cloud storage.
  ossFilePrefix: 'https://your-cloud-storage.com/',
  // (Optional) Add additional information.
  extraInfo: 'This is some additional information for content inspection.',
  // Set the function type to \"supervise\".
  inspectType: ['supervise'],
};

client
  .enableContentInspect(inspectConfig)
  .then(() => {
    console.log('Content inspection enabled successfully.');
  })
  .catch((error) => {
    console.error('Failed to enable content inspection:', error);
  });

HTTP notification callback

After a screenshot is successfully uploaded to the Agora SDRTN®, Agora sends a message notification callback to your application server in the form of an HTTPS POST request. The data format is JSON, and the character encoding is UTF-8.

Upon receiving the message notification, your application server must respond with status code 200. The expected response body format is JSON. In any of the following cases, the notification is considered to have failed:

• No response is received from your server within 5 seconds after sending the message notification.
• The HTTP status code of the response is not 200, or the response body format is not JSON.

The Agora service immediately retries after the first notification failure, and sends the message three times in total.

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Pricing

Agora charges for local screenshot upload based on two metrics:

• Screenshot fee
• QPS overage fee (queries per second)

local screenshot upload dynamic library

You can find details about the name of the local screenshot upload dynamic library and the increase in app size after integration in App size optimization.

HTTP status codes

The HTTP status codes for the application server responses are as follows: