# 插件 (/zh-CN/api-reference/rtc/android/4.6.0/extensions)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## addExtension [#addextension]
添加扩展。
```java
public void addExtension(String providerName)
```
### 参数 [#参数]
#### `providerName` [#providername]
要添加的扩展名称。
### 所属接口类 [#所属接口类]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## enableExtension [#enableextension]
启用或禁用扩展功能。
```java
public abstract int enableExtension(String provider, String extension, boolean enable);
```
通过调用该方法,你可以动态启用或禁用扩展功能,而无需更改处理流程。
:::info[注]
[enableExtension](/zh-CN/api-reference/rtc/android/extensions#api_irtcengine_enableextension) 会在未调用 [registerExtension](/zh-CN/api-reference/rtc/android/extensions#api_irtcengine_registerextension) 的情况下自动注册指定扩展,以保证兼容性。建议你显式调用 [registerExtension](/zh-CN/api-reference/rtc/android/extensions#api_irtcengine_registerextension)。
:::
### 参数 [#参数-1]
#### `provider` [#provider]
扩展功能提供方的名称,例如 `agora.io`。
#### `extension` [#extension]
扩展功能的名称,例如 `agora.beauty`。
#### `enable` [#enable]
是否启用该扩展功能:
- true:(默认)启用扩展功能。
- false:禁用扩展功能。
### 返回值 [#返回值]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## getExtensionProperty [1/2] [#getextensionproperty-12]
获取扩展组件的详细信息。
```java
public abstract String getExtensionProperty(String provider, String extension, String key);
```
### 调用时机 [#调用时机]
该方法可以在加入频道前或加入频道后调用。
### 参数 [#参数-2]
#### `provider` [#provider-1]
扩展组件提供方的名称。
#### `extension` [#extension-1]
扩展组件的名称。
#### `key` [#key]
扩展组件的键值。
### 返回值 [#返回值-1]
- 方法调用成功时,返回扩展组件的信息。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-2]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## getExtensionProperty [2/2] [#getextensionproperty-22]
获取扩展组件的详细信息。
```java
public abstract String getExtensionProperty(String provider, String extension, String key, Constants.MediaSourceType sourceType);
```
### 调用时机 [#调用时机-1]
该方法可以在加入频道前或加入频道后调用。
### 参数 [#参数-3]
#### `provider` [#provider-2]
扩展组件提供方的名称。
#### `extension` [#extension-2]
扩展组件的名称。
#### `key` [#key-1]
扩展组件的键值。
#### `sourceType` [#sourcetype]
扩展组件的来源类型,详见 [MediaSourceType](/zh-CN/api-reference/rtc/android/class-and-enum/enums/enum-mediasourcetype)。
### 返回值 [#返回值-2]
- 方法调用成功时,返回扩展组件的信息。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-3]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## registerExtension [#registerextension]
注册一个扩展。
```java
public abstract int registerExtension(String provider, String extension, Constants.MediaSourceType sourceType);
```
- 对于 SDK 外部的扩展(例如来自云市场和 SDK 扩展),你需要在调用 registerExtension 之前先通过 addExtension 加载它们。
- 对于 SDK 内部的扩展(即包含在完整 SDK 包中的扩展),在初始化 RtcEngine 后会自动加载并注册。
注:
- 如果你想注册多个扩展,需要多次调用此方法。
- SDK 中不同扩展的数据处理顺序由注册顺序决定。即先注册的扩展会先处理数据。
### 调用时机 [#调用时机-2]
声网建议你在初始化 [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine) 后、加入频道前调用此方法。
- 对于视频扩展(如美颜特效扩展),你需要在调用 enableVideo 或 enableLocalVideo 启用视频模块后再调用此方法。
- 在调用此方法之前,你需要先调用 addExtension 加载扩展。
### 参数 [#参数-4]
#### `provider` [#provider-3]
扩展提供方的名称。
#### `extension` [#extension-3]
扩展的名称。
#### `sourceType` [#sourcetype-1]
扩展的数据源类型,详见 [MediaSourceType](/zh-CN/api-reference/rtc/android/class-and-enum/enums/enum-mediasourcetype)。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
- -3:扩展库未加载。建议你检查动态库的存储位置或名称。
### 所属接口类 [#所属接口类-4]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## setExtensionProperty [#setextensionproperty]
设置扩展组件的属性。
```java
public abstract int setExtensionProperty(String provider, String extension, String key, String value);
```
启用扩展组件后,可以调用该方法设置其属性。
:::info[注]
如果你需要为多个扩展组件设置属性,需要多次调用该方法。
:::
### 调用时机 [#调用时机-3]
在调用 [enableExtension](/zh-CN/api-reference/rtc/android/extensions#api_irtcengine_enableextension) 方法之后调用该方法。
### 参数 [#参数-5]
#### `provider` [#provider-4]
扩展组件提供方的名称。
#### `extension` [#extension-4]
扩展组件的名称。
#### `key` [#key-2]
扩展组件属性的键。
#### `value` [#value]
扩展组件属性键对应的值。
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## setExtensionProviderProperty [#setextensionproviderproperty]
设置扩展提供方的属性。
```java
public abstract int setExtensionProviderProperty(String provider, String key, String value);
```
你可以调用该方法根据扩展提供方的类型初始化相关参数。
:::info[注]
如果你想为多个扩展设置扩展提供方的属性,需要多次调用该方法。
:::
### 调用时机 [#调用时机-4]
在调用 [enableExtension](/zh-CN/api-reference/rtc/android/extensions#api_irtcengine_enableextension) 之前, [registerExtension](/zh-CN/api-reference/rtc/android/extensions#api_irtcengine_registerextension) 之后调用该方法。
### 参数 [#参数-6]
#### `provider` [#provider-5]
扩展提供方的名称。
#### `key` [#key-3]
扩展属性的键名。
#### `value` [#value-1]
扩展属性键对应的值。
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-6]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## onErrorWithContext [#onerrorwithcontext]
扩展运行异常时触发的回调。
```java
default void onErrorWithContext(ExtensionContext extContext, int error, String message)
```
### 触发时机 [#触发时机]
该回调在扩展启用失败或运行过程中发生错误时被触发。
### 参数 [#参数-7]
#### `extContext` [#extcontext]
扩展的上下文信息。详见 [ExtensionContext](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-extensioncontext)。
#### `error` [#error]
错误码。
#### `message` [#message]
错误原因。
### 所属接口类 [#所属接口类-7]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler)
## onEventWithContext [#oneventwithcontext]
扩展事件回调。
```java
default void onEventWithContext(ExtensionContext extContext, String key, String value)
```
你需要注册该回调,用于在扩展运行期间监听事件。
### 参数 [#参数-8]
#### `extContext` [#extcontext-1]
扩展的上下文信息,详见 [ExtensionContext](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-extensioncontext)。
#### `key` [#key-4]
扩展事件的键。
#### `value` [#value-2]
扩展事件键对应的值。
### 所属接口类 [#所属接口类-8]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler)
## onStartedWithContext [#onstartedwithcontext]
扩展启用成功回调。
```java
default void onStartedWithContext(ExtensionContext extContext)
```
### 触发时机 [#触发时机-1]
该回调在扩展成功启用后被触发。
### 参数 [#参数-9]
#### `extContext` [#extcontext-2]
扩展的上下文信息。详见 [ExtensionContext](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-extensioncontext)。
### 所属接口类 [#所属接口类-9]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler)
## onStoppedWithContext [#onstoppedwithcontext]
扩展被禁用时触发的回调。
```java
default void onStoppedWithContext(ExtensionContext extContext)
```
### 触发时机 [#触发时机-2]
该回调在扩展被成功禁用后触发。
### 参数 [#参数-10]
#### `extContext` [#extcontext-3]
扩展的上下文信息。详见 [ExtensionContext](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-extensioncontext)。
### 所属接口类 [#所属接口类-10]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler)