Extensions

addExtension

Adds an extension.

public void addExtension(String providerName)

Parameters

providerName: Name of the extension to add.

enableExtension

Enables or disables an extension feature.

public abstract int enableExtension(String provider, String extension, boolean enable);

You can dynamically enable or disable an extension feature by calling this method without changing the processing flow.

Note: enableExtension automatically registers the specified extension if registerExtension is not called, to ensure compatibility. It is recommended to explicitly call registerExtension.

Parameters

provider

The name of the extension provider, e.g., agora.io.

extension

The name of the extension feature, e.g., agora.beauty.

enable

Whether to enable the extension feature:

true: (default) Enable the extension feature.
false: Disable the extension feature.

Return Values

0: Success.
< 0: Failure.

getExtensionProperty [1/2]

Gets detailed information of an extension component.

public abstract String getExtensionProperty(String provider, String extension, String key);

Timing

You can call this method before or after joining the channel.

Parameters

provider: The name of the extension component provider.
extension: The name of the extension component.
key: The key of the extension component.

Return Values

On success, returns the information of the extension component.
On failure, returns an empty string.

getExtensionProperty [2/2]

Gets detailed information of an extension component.

public abstract String getExtensionProperty(String provider, String extension, String key, Constants.MediaSourceType sourceType);

Timing

You can call this method before or after joining the channel.

Parameters

provider: The name of the extension component provider.
extension: The name of the extension component.
key: The key of the extension component.
sourceType: The source type of the extension component. See MediaSourceType.

Return Values

On success, returns the information of the extension component.
On failure, returns an empty string.

registerExtension

Registers an extension.

public abstract int registerExtension(String provider, String extension, Constants.MediaSourceType sourceType);

For external SDK extensions (e.g., from the cloud marketplace or SDK extensions), you must load them using addExtension before calling registerExtension.
For internal SDK extensions (included in the full SDK package), they are automatically loaded and registered after initializing RtcEngine.

Note:

To register multiple extensions, call this method multiple times.
The processing order of different extensions in the SDK is determined by the registration order. Extensions registered earlier process data first.

Timing

Agora recommends calling this method after initializing RtcEngine and before joining a channel.

For video extensions (e.g., beauty effects), call this method after enabling the video module using enableVideo or enableLocalVideo.
Before calling this method, you must call addExtension to load the extension.

Parameters

provider: The name of the extension provider.
extension: The name of the extension.
sourceType: The data source type of the extension. See MediaSourceType.

Return Values

0: Success.
< 0: Failure.
- -3: The extension library is not loaded. Check the storage location or name of the dynamic library.

setExtensionProperty

Sets the properties of an extension component.

public abstract int setExtensionProperty(String provider, String extension, String key, String value);

After enabling the extension component, you can call this method to set its properties.

Note: To set properties for multiple extension components, call this method multiple times.

Timing

Call this method after calling enableExtension.

Parameters

provider: The name of the extension component provider.
extension: The name of the extension component.
key: The key of the extension component property.
value: The value corresponding to the extension component property key.

Return Values

0: Success.
< 0: Failure.

setExtensionProviderProperty

Sets the properties of the extension provider.

public abstract int setExtensionProviderProperty(String provider, String key, String value);

You can call this method to initialize parameters based on the type of the extension provider.

Note: To set properties for multiple extensions, call this method multiple times.

Timing

Call this method after registerExtension and before enableExtension.

Parameters

provider: The name of the extension provider.
key: The key name of the extension property.
value: The value corresponding to the extension property key.

Return Values

0: Success.
< 0: Failure.

onErrorWithContext

Callback triggered when an error occurs during extension runtime.

default void onErrorWithContext(ExtensionContext extContext, int error, String message)

Trigger Timing

This callback is triggered when the extension fails to start or an error occurs during runtime.

Parameters

extContext: Context information of the extension. See ExtensionContext.
error: Error code.
message: Error reason.

onEventWithContext

Extended event callback.

default void onEventWithContext(ExtensionContext extContext, String key, String value)

You need to register this callback to listen for events during extension runtime.

Parameters

extContext: Context information of the extension. See ExtensionContext.
key: Key of the extension event.
value: Value corresponding to the extension event key.

onStartedWithContext

Callback for successful extension enablement.

default void onStartedWithContext(ExtensionContext extContext)

Trigger Timing

This callback is triggered after the extension is successfully enabled.

Parameters

extContext: Context information of the extension. See ExtensionContext.

onStoppedWithContext

Callback triggered when the extension is disabled.

default void onStoppedWithContext(ExtensionContext extContext)

Trigger Timing

This callback is triggered after the extension is successfully disabled.

Parameters

extContext: Context information of the extension. See ExtensionContext.