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