# 插件 (/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)