# Meta SDK API (/zh-CN/solutions/meta-world/reference/meta-api) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). <_PlatformTabsGroup> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="android" /> 本文介绍声网 Meta SDK 的 Java API。 ## 概述 [#概述] Meta SDK 是基于声网视频 SDK 开发的元系列特殊版 SDK。相比[视频 SDK](/zh-CN/realtime-media/rtc),Meta SDK 中新增元系列相关的 API。 Meta SDK 各接口类之间的关系如下图所示: ## IMetaService [#imetaservice] 提供 Meta 服务的核心类。可用于获取场景资源列表、下载场景资源、删除本地场景资源等场景资源管理,还可用于创建 `IMetaScene`。 ### create [#create] ```java public static synchronized IMetaService create(); ``` 创建 `IMetaService` 对象。 **返回值** `IMetaService` 对象。 ### initialize [#initialize] ```java public abstract int initialize(MetaServiceConfig config); ``` 初始化 `IMetaService` 对象并登录声网 RTM 系统。 **参数** `config`:初始化 `IMetaService` 对象需要的配置信息,详见 [`MetaServiceConfig`](#metaserviceconfig)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### destroy [#destroy] ```java public static synchronized void destroy() ``` 销毁 `IMetaService` 对象。 ### addEventHandler [#addeventhandler] ```java public abstract int addEventHandler(IMetaServiceEventHandler eventHandler); ``` 添加事件句柄。 **参数** `eventHandler`:事件句柄:`IMetaServiceEventHandler`。 **返回值** - 0:方法调用成功 - < 0:添加事件句柄失败 ### removeEventHandler [#removeeventhandler] ```java public abstract int removeEventHandler(IMetaServiceEventHandler eventHandler); ``` 移除事件句柄。 **参数** `eventHandler`:事件句柄:`IMetaServiceEventHandler`。 **返回值** - 0:方法调用成功 - < 0:移除事件句柄失败 ### renewToken [#renewtoken] ```java public abstract int renewToken(String token); ``` 更新 Token。 Token 有有效期,在过期前 SDK 会触发 [`onTokenWillExpire`](#ontokenwillexpire) 回调报告 Token 即将过期。此时,你需要在服务器生成新的 Token,然后调用 `renewToken` 并在参数里传入新 Token。 ### getSceneAssetsInfo [#getsceneassetsinfo] ```java public abstract int getSceneAssetsInfo(); ``` 获取场景列表。 调用该方法会触发 [`onGetSceneAssetsInfoResult`](#ongetsceneassetsinforesult) 回调。 **返回值** - 0:方法调用成功 - < 0:获取场景场景列表失败 ### isSceneAssetsDownloaded [#issceneassetsdownloaded] ```java public abstract int isSceneAssetsDownloaded(long sceneId); ``` 判断场景场景是否已下载到本地。 **参数** `sceneId`:场景场景的 ID,可以从 [`MetaSceneAssetsInfo`](#metasceneassetsinfo) 获取。 **返回值** - 0:未下载到本地。 - 1:已下载到本地。 ### downloadSceneAssets [#downloadsceneassets] ```java public abstract int downloadSceneAssets(long sceneId); ``` 下载场景资源到本地。 调用该方法会触发 `IMetaServiceEventHandler` 类的 `onDownloadSceneProgress` 回调。 **参数** `sceneId`:场景资源的 ID,可以从 [`MetaSceneAssetsInfo`](#metasceneassetsinfo) 获取。 **返回值** - 0:下载成功 - < 0:下载失败 ### cancelDownloadSceneAssets [#canceldownloadsceneassets] ```java public abstract int cancelDownloadSceneAssets(long sceneId); ``` 取消下载场景资源到本地。 调用该方法会触发 `IMetaServiceEventHandler` 类的 `onDownloadSceneProgress` 回调,其中 `state` 为 `3(FAILED)`。 调用该方法后如果再次调用 `downloadSceneAssets`,会从上次取消下载时的进度恢复下载。 **参数** `sceneId`:场景资源的 ID,可以从 [`MetaSceneAssetsInfo`](#metasceneassetsinfo) 获取。 **返回值** - 0:取消下载成功 - < 0:取消下载失败 ### cleanSceneAssets [#cleansceneassets] ```java public abstract int cleanSceneAssets(long sceneId); ``` **参数** `sceneId`:场景资源的 ID,可以从 [`MetaSceneAssetsInfo`](#metasceneassetsinfo) 获取。 **返回值** - 0:清理成功 - < 0:清理失败 ### createScene [#createscene] ```java public abstract int createScene(MetaSceneConfig config); ``` 创建 `IMetaScene` 对象。 调用该方法会触发 `IMetaServiceEventHandler` 类的 [`onCreateSceneResult`](#oncreatesceneresult) 回调。成功创建的 `IMetaScene` 对象可以在该回调里拿到。 **参数** `config`:创建 `IMetaScene` 对象需要的配置信息,详见 [`MetaSceneConfig`](#metasceneconfig)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ## IMetaScene [#imetascene] 场景资源相关操作。 ### release [#release] ```java public abstract int release(); ``` 销毁 `IMetaScene` 对象。 调用该方法会触发 [`onReleasedScene`](#onreleasedscene) 回调。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### getLocalUserAvatar [#getlocaluseravatar] ```java public abstract ILocalUserAvatar getLocalUserAvatar(); ``` 获取 `ILocalUserAvatar` 对象。 进入场景前,可以调用该方法获取用户的昵称、虚拟形象、装扮捏脸等信息。 **返回值** `ILocalUserAvatar` 对象。 ### addEventHandler [#addeventhandler-1] ```java public abstract int addEventHandler(IMetaSceneEventHandler eventHandler); ``` 添加事件句柄。 **参数** `eventHandler`:事件句柄:`IMetaServiceEventHandler`。 **返回值** - 0:方法调用成功 - < 0:添加事件句柄失败 ### removeEventHandler [#removeeventhandler-1] ```java public abstract int removeEventHandler(IMetaServiceEventHandler eventHandler); ``` 移除事件句柄。 **参数** `eventHandler`:事件句柄:`IMetaServiceEventHandler`。 **返回值** - 0:方法调用成功 - < 0:移除事件句柄失败 ### enterScene [#enterscene] ```java public abstract int enterScene(EnterSceneConfig config); ``` 进入场景。 成功调用该方法会触发 `IMetaSceneEventHandler` 类的 [`onEnterSceneResult`](#onentersceneresult) 回调。 **参数** `config`:进入场景所需要的配置信息,详见 [`EnterSceneConfig`](#entersceneconfig)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### leaveScene [#leavescene] ```java public abstract int leaveScene(); ``` 离开场景。 成功调用该方法会触发 `IMetaSceneEventHandler` 类的 [`onLeaveSceneResult`](#onleavesceneresult) 回调。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### sendSceneMessage [#sendscenemessage] ```java public abstract int sendSceneMessage(byte[] message); ``` 往场景发送自定义消息。 该方法适用于 App 需要和 Unity 通信的场景资源。Unity 收到自定义消息后可以进行自定义的逻辑处理。 :::warning[注意] 该方法必须在 `enterScene` 之后调用。 ::: **参数** `message`:自定义消息,目前只支持字符串。消息格式可以自定义。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### setSceneParameters [#setsceneparameters] ```java public abstract int setSceneParameters(String jsonParam); ``` (预留方法,尚未实现)设置场景渲染相关参数。 ### enableVideoDisplay [#enablevideodisplay] ```java public abstract int enableVideoDisplay(String displayId, boolean enable); ``` 开启/关闭场景里的视频显示器。 **参数** - `displayId`:指定显示器的 ID。该 ID 需要由你的 Native 开发人员和 Unity 开发人员协商后规定。 - `enable`:是否开启指定显示器: - `true`:开启显示器,即开始视频渲染。 - `false`:关闭显示器,即关闭视频渲染。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### pushVideoFrameToDisplay [#pushvideoframetodisplay] ```java public abstract int pushVideoFrameToDisplay(String displayId, AgoraVideoFrame frame); ``` 往场景里的视频显示器推送原始视频帧。 **参数** - `displayId`:指定显示器的 ID。ID 需要由你的 Native 开发人员和 Unity 开发人员协商后规定。 - `frame`:原始视频帧。详见 RTC SDK API 参考中的 [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/android/class-externalvideoframe)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### addSceneView [#addsceneview] ```java public abstract int addSceneView(TextureView view, SceneDisplayConfig config); ``` 添加场景显示视图。 调用该方法在场景中添加一个视图,用于在频道内发布主播的 Avatar 形象。调用成功后,SDK 会触发 `IMetaSceneEventHandler` 协议的 [`onAddSceneViewResult`](#onaddsceneviewresult) 回调。 **参数** - `view`:视频视图。 - `config`:场景显示相关配置参数,[`SceneDisplayConfig`](#scenadiaplayconfig)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### removeSceneView [#removesceneview] ```java public abstract int removeSceneView(TextureView view); ``` 移除场景显示视图。 调用成功后,SDK 会触发 `IMetaSceneEventHandler` 类的 [`onRemoveSceneViewResult`](#onremovesceneviewresult) 回调。 **参数** `view`:待移除的视图。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### enableSceneVideoCapture [#enablescenevideocapture] ```java public abstract int enableSceneVideoCapture(TextureView view, boolean enable); ``` 开启或关闭场景渲染画面捕获。 该方法用于开启或关闭场景渲染画面捕获。通过与 `RtcEngine` 的 [`joinChannel` [2/2]](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_joinchannel2) 方法配合使用,可以将场景渲染的画面发布到 RTC 频道中。 **参数** - `view`:需要捕获的场景视图。 - `enable`:是否开启场景渲染画面捕获。 - `true`:开启。场景画面会发布到 RTC 频道中。 - `false`:(默认)不开启。场景画面不会发不到 RTC 频道中。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ## ILocalUserAvatar [#ilocaluseravatar] 包含在 `IMetaScene` 中,生命周期和 `IMetaScene` 相同,用于设置虚拟形象(Avatar)。 ### setUserInfo [#setuserinfo] ```java int setUserInfo(MetaUserInfo userInfo); ``` 设置用户的基本信息。 **参数** `userInfo`:在场景内展示的用户信息,详见 [`MetaUserInfo`](#metauserinfo)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### getUserInfo [#getuserinfo] ```java MetaUserInfo getUserInfo(); ``` 获取用户的基本信息。 **返回值** [`MetaUserInfo`](#metauserinfo) 对象。 ### setModelInfo [#setmodelinfo] ```java int setModelInfo(AvatarModelInfo modelInfo); ``` 设置用户的模型信息。 **参数** `modelInfo`:用户的虚拟形象模型信息,详见 [`AvatarModelInfo`](#avatarmodelinfo)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### getModelInfo [#getmodelinfo] ```java AvatarModelInfo getModelInfo(); ``` 获取当前使用的用户模型信息。 **返回值** [`AvatarModelInfo`](#avatarmodelinfo) 对象。 ### setExtraInfo [#setextrainfo] ```java int setExtraInfo(byte[] extraInfo); ``` 设置自定义的用户信息。 你可以通过该方法设置用户的装扮信息、捏脸信息。 **参数** `extraInfo`:自定义的用户信息。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### getExtraInfo [#getextrainfo] ```java byte[] getExtraInfo(); ``` 获取自定义的用户信息。 **返回值** 当前使用的自定义的用户信息。 ### applyInfo [#applyinfo] ```java int applyInfo(); ``` 应用新设置的用户信息。 :::warning[注意] - 如果你在进入场景资源前调用 `setUserInfo`、`setModelInfo`、`setExtraInfo` 方法,则不需要调用 `applyInfo`。 - 如果你在进入场景资源后调用了 `setUserInfo`、`setModelInfo`、`setExtraInfo` 方法,必须再调用 `applyInfo` 让设置的信息生效。 ::: **返回值** - 0:方法调用成功 - < 0:方法调用失败 ## IMetaServiceEventHandler [#imetaserviceeventhandler] `IMetaService` 的异步方法的事件回调类。 ### onCreateSceneResult [#oncreatesceneresult] ```java public void onCreateSceneResult(IMetaScene scene, int errorCode); ``` `IMetaScene` 创建回调。 **参数** - `scene`:创建的 `IMetaScene` 对象,用于后续进出场景等操作。 - `errorCode`:错误码: - 0 表示创建成功。 - 其余情况表示创建失败。 ### onConnectionStateChanged [#onconnectionstatechanged] ```java public void onConnectionStateChanged(int state, int reason); ``` 连接状态改变回调。 **参数** - `state`:连接状态。 - `1`:断开连接。 - `2`:正在连接。 - `3`:连接成功。 - `4`:正在重连。 - `5`:连接丢弃。 - `reason`:连接状态改变的原因。 ### onTokenWillExpire [#ontokenwillexpire] ```java public void onTokenWillExpire(); ``` Token 即将过期回调。 收到该回调后,你需要在服务器生成新的 Token,然后调用 [`renewToken`](#renewtoken) 并在参数里传入新 Token。 ### onGetSceneAssetsInfoResult [#ongetsceneassetsinforesult] ```java public void onGetSceneAssetsInfoResult(MetaSceneAssetsInfo[] metaSceneAssetsInfo, int errorCode); ``` 获取场景资源列表回调。 **参数** - `metaSceneAssetsInfo`:场景资源信息列表,详见 [`MetaSceneAssetsInfo`](#metasceneassetsinfo)。 - `errorCode`:错误码: - 0 表示获取列表成功。 - 其余情况表示获取列表失败。 ### onDownloadSceneAssetsProgress [#ondownloadsceneassetsprogress] ```java public void onDownloadSceneAssetsProgress(long sceneId, int progress, int state); ``` 下载场景资源进度回调。 **参数** - `sceneId`:场景资源 ID。 - `progress`:下载进度,取值范围 [0,100]。 - `state`:下载状态: - `0`:空闲。 - `1`:正在下载。 - `2`:下载完成。 - `3`:下载失败 ## IMetaSceneEventHandler [#imetasceneeventhandler] `IMetaScene` 的异步方法的事件回调类。 ### onEnterSceneResult [#onentersceneresult] ```java public void onEnterSceneResult(int errorCode); ``` 进入场景的结果回调。 **参数** `errorCode`:错误码: - 0 表示进入场景成功。 - 其余情况进入场景失败。 ### onLeaveSceneResult [#onleavesceneresult] ```java public void onLeaveSceneResult(int errorCode); ``` 离开场景的结果回调。 **参数** `errorCode`:错误码: - 0 表示离开场景成功。 - 其余情况离开场景失败。 ### onSceneMessageReceived [#onscenemessagereceived] ```java public void onSceneMessageReceived(byte[] message);public void onSceneMessageReceived(byte[] message); ``` 接收场景信息回调。 App 收到 Unity 场景发送的自定义信息时,SDK 会触发该回调。 **参数** `message`:自定义格式的消息。目前只支持字符串。 ### onUserPositionChanged [#onuserpositionchanged] ```java public void onUserPositionChanged(String uid, MetaUserPositionInfo posInfo); ``` 本地或远端用户位置变化回调。 用户位置变化时,SDK 会触发该回调。 **参数** - `uid`:本地或远端用户的用户 ID。 - `posInfo`:用户的位置信息,详见 [`MetaUserPositionInfo`](#metauserpositioninfo)。 ### onReleasedScene [#onreleasedscene] ```java void onReleasedScene(int status); ``` `IMetaScene` 释放回调。 **参数** `status`:错误码: - 0 表示释放 `IMetaScene` 成功。 - 其余情况释放 `IMetaScene` 失败。 ### onAddSceneViewResult [#onaddsceneviewresult] ```java void onAddSceneViewResult(TextureView view, int errorCode); ``` 添加场景显示视图回调。 调用 `IMetaScene` 类的 `addSceneView` 方法添加场景显示视图后,SDK 会触发该回调。 **参数** - `view`:视图对象:`TextureView`。 - `errorCode`:错误码: - 0 表示添加视图成功。 - 其余情况添加视图失败。 ### onRemoveSceneViewResult [#onremovesceneviewresult] ```java void onRemoveSceneViewResult(TextureView view, int errorCode); ``` 移除场景显示视图回调。 调用 `IMetaScene` 类的 `removeSceneView` 方法移除场景显示视图后,SDK 会触发该回调。 **参数** - `view`:视图对象:`TextureView`。 - `errorCode`:错误码: - 0 表示移除视图成功。 - 其余情况移除视图失败。 ## 类型定义 [#类型定义] ### MetaServiceConfig [#metaserviceconfig] 初始化 `IMetaService` 对象的配置信息。 ```java public class MetaServiceConfig { public RtcEngine mRtcEngine; public String mAppId; public String mRtmToken; public String mLocalDownloadPath; public String mUserId; public IMetaServiceEventHandler mEventHandler; } ``` - `mRtcEngine`:`RtcEngine` 实例,创建方法详见 [`create` [1/2]](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_create)。 - `mAppId`:在声网控制台获取的 App ID。 - `mRtmToken` :用于登录声网 RTM 系统的动态密钥。开启动态鉴权后可用。 - `mLocalDownloadPath` :场景资源下载到本地的保存路径。 - `mUserId`:登录声网 RTM 系统的用户 ID。该字符串不可超过 64 字节。可以通过以下方式和声网 RTC 用户 ID 绑定: - (推荐)使用 Int 型的 RTC 用户 ID,RTM 用户 ID 设为相同的数字字符串。 - 使用 String 型的 RTC 用户 ID,RTM 用户 ID 设为相同的字符串。 - 使用 Int 型的 RTC 用户 ID,RTM 用户 ID 设为不同的数字字符串,并且自行维护二者的映射关系。 - `mEventHandler`:回调事件,详见 [`IMetaServiceEventHandler`](#imetaserviceeventhandler)。 ### MetaUserInfo [#metauserinfo] 用户信息。 ```java public class MetaUserInfo { public String mUserId; public String mUserName; public String mUserIconUrl; } ``` - `mUserId`:登录声网 RTM 系统的用户 ID。该字符串不可超过 64 字节。可以通过以下方式和声网 RTC 用户 ID 绑定: - (推荐)使用 Int 型的 RTC 用户 ID,RTM 用户 ID 设为相同的数字字符串。 - 使用 String 型的 RTC 用户 ID,RTM 用户 ID 设为相同的字符串。 - 使用 Int 型的 RTC 用户 ID,RTM 用户 ID 设为不同的数字字符串,并且自行维护二者的映射关系。 - `mUserName`:用户昵称,用于在场景内显示用户昵称。 - `mUserIconUrl`:用户头像的 URL,用于在场景内显示用户头像。 ### MetaSceneAssetsInfo [#metasceneassetsinfo] 场景资源信息。 ```java public class MetaSceneAssetsInfo { public long mSceneId; public String mSceneName; public String mThumbnailPath; public String mScenePath; public String mParentScenePath; public String mDescription; public String mSceneConfig; public String mExtraInfo; public MetaBundleInfo[] mBundles; public String mSceneVersion; public String mSceneLocalVersion; public long mTotalSize; } ``` - `mSceneId`:场景资源的唯一标识符。 - `mSceneName`:场景资源名称。 - `mThumbnailPath`:场景资源缩略图的本地路径。 - `mScenePath`:场景场景的本地路径。 - `mParentScenePath`:依赖的父场景场景的本地路径。 - `mDescription`:场景资源的文字描述。 - `mSceneConfig`:场景资源的配置信息。 - `mExtraInfo`:其它额外信息。 - `mBundles`:场景资源支持的资源包列表。 - `mSceneVersion`:场景场景在服务器上的版本号。 - `mSceneLocalVersion`:场景场景在本地的版本号。 - `mTotalSize`:场景场景包总大小。 ### MetaBundleInfo [#metabundleinfo] 资源包信息。 ```java public class MetaBundleInfo { public long mBundleId; public long mSceneId; public int mBundleType; public String mBundleCode; public String mBundleName; public String mDescription; public String mBundlePath; public String mThumbnailPath; public String mAssets; public String mExtraInfo; public long mBundleSize; } ``` - `mBundleId`:资源包 ID。不同平台(Android、iOS)的同一个资源包的 ID 是不同的。 - `mSceneId`:所属的场景资源 ID。 - `mBundleType`:资源包类型: - `1`:场景场景。 - `2`:虚拟形象(Avatar)资源。 - `3`:assetManifest 资源。 - `100`:其他资源。 - `mBundleCode`:资源包代码,不同平台(Android、iOS)同一个资源包的代码要保持一致。 - `mBundleName`:资源包名称。 - `mDescription`:资源包描述。 - `mBundlePath`:资源包的本地存储路径。 - `mThumbnailPath`:资源包缩略图的本地存储路径。 - `mAssets`:预留参数。 - `mExtraInfo`:资源包的其它额外信息。 - `mBundleSize`:资源包大小。 ### MetaSceneConfig [#metasceneconfig] 场景资源的配置信息。 ```java public class MetaSceneConfig { public int mSyncMode; public Context mActivityContext; public boolean mEnableFaceCapture; public String mFaceCaptureAppId; public String mFaceCaptureCertificate; } ``` - `mSyncMode`:消息同步模式: - `STATE_SYNC_MODE_NONE(0)`:不同步消息。 - `STATE_SYNC_MODE_NORMAL(1)`:(默认)通过 RTM 同步消息。 - `mActivityContext`:Activity 的 Context 对象,用于初始化 Unity。 - `mEnableFaceCapture`:是否开启面部捕捉: - `true`:开启。 - `false`:(默认)不开启。 - `mFaceCaptureAppId`:开启面部捕捉时设置的 App ID。开启面捕时必填。 - `mFaceCaptureCertificate`:开启面部捕捉时设置的 Certificate(证书)。开启面捕时必填。 通过面捕 App ID 和 Certificate 可以获取对应的面捕证书(license)。开启面捕功能时,需要你设置面捕证书(license)。 ### EnterSceneConfig [#entersceneconfig] 进入场景的配置信息。 ```java public class EnterSceneConfig { public String mRoomName; public TextureView mSceneView; public long mSceneId; public String mScenePath; public byte[] mExtraInfo; } ``` - `mRoomName`:进入场景的房间名称。 - `mSceneView`:场景资源渲染所需要的视图。Android 上用原生的 [TextureView](https://developer.android.com/reference/android/view/TextureView) 对象即可。 - `mSceneId`:进入场景的 ID。 - `mScenePath`:(可选)`mSceneId` 为 0 时,表示从本地路径加载资源,此时,`mScenePath` 必须设为本地资源文件夹的路径。 - `mExtraInfo`:(可选)加载场景资源时需要的其它额外自定义信息。你可以自行定义,目前只支持字符串。 ### AvatarModelInfo [#avatarmodelinfo] 用户的虚拟形象(Avatar)信息。 ```java public class AvatarModelInfo { public String mBundleCode; public boolean mLocalVisible; public boolean mRemoteVisible; public boolean mSyncPosition; } ``` - `mBundleCode`:人物模型所在的资源包代码。 - `mLocalVisible`:虚拟人物模型是否在本地可见。如果设为 `false`,`mRemoteVisible` 和 `mSyncPosition` 会自动设为 `false`,并且无法更改。 - `mRemoteVisible`:虚拟人物模型是否在远端可见。 - `mSyncPosition`:是否同步本地人物渲染时所需要的信息(例如模型、装扮、捏脸信息等),用于控制玩家和游客模式。如果设为 `false`,`mRemoteVisible` 不生效。 ### MetaUserPositionInfo [#metauserpositioninfo] 用户的位置信息。 ```java public class MetaUserPositionInfo { public float[] mPosition; public float[] mForward; public float[] mRight; public float[] mUp; } ``` - `mPosition`:用户的坐标位置。 - `mForward`:用户朝向的三维向量。 - `mRight`:用户右手方向的向量。 - `mUp`:用户头朝向的向量。 ### SceneDisplayConfig [#scenedisplayconfig] 场景显示相关配置。 ```java public class SceneDisplayConfig { public int width; public int height; public byte[] extraInfo; } ``` - `width`:场景渲染画面的宽。 - `height`:场景渲染画面的高度。该宽高决定拿到场景渲染画面的原始视频帧的大小。如果要将画面发布到 RTC 频道中,建议将该宽高设置为与 RTC 的视频编码参数宽高一致,以避免缩放裁剪导致的性能损耗。 - `extraInfo`:Unity 渲染场景所需的额外信息,该字段是用户自定义的,一般由你的 Native 开发人员和 Unity 开发人员约定好。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="ios" /> 本文介绍声网 Meta SDK 的 Objective-C API。 ## 概述 [#概述-1] Meta SDK 是基于声网视频 SDK 开发的元系列特殊版 SDK。相比[视频 SDK](/zh-CN/api-reference/rtc/ios/rtc-api-overview),Meta SDK 中新增元系列相关的 API。 ## AgoraMetaServiceKit [#agorametaservicekit] Meta SDK 所有接口的入口,可用于获取场景资源列表、下载场景资源、删除本地场景资源等场景资源管理,还可用于创建 `AgoraMetaScene`。 ### sharedMetaServiceWithConfig [#sharedmetaservicewithconfig] ```objc + (instancetype _Nonnull)sharedMetaServiceWithConfig:(AgoraMetaServiceConfig* _Nonnull)config NS_SWIFT_NAME(sharedMetaServiceWithConfig(_:)); ``` 创建和初始化 `AgoraMetaServiceKit` 对象,并且登录声网 RTM 系统。 **参数** `config`:初始化 `AgoraMetaServiceKit` 对象需要的配置信息,详见 [`AgoraMetaServiceConfig`](#agorametaserviceconfig)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### destroy [#destroy-1] ```objc + (void)destroy NS_SWIFT_NAME(destroy()); ``` 销毁 `AgoraMetaServiceKit` 对象。 ### renewToken [#renewtoken-1] ```objc - (NSInteger)renewToken:(NSString *_Nonnull)token; ``` 更新 Token。 Token 有有效期,在过期前 SDK 会触发 [`onTokenWillExpire`](#ontokenwillexpire) 回调报告 Token 即将过期。此时,你需要在服务器生成新的 Token,然后调用 `renewToken` 并在参数里传入新 Token。 ### getSceneAssetsInfo [#getsceneassetsinfo-1] ```objc - (NSInteger)getSceneAssetsInfo; ``` 获取场景列表。 调用该方法会触发 [`onGetSceneAssetsInfoResult`](#ongetsceneassetsinforesult) 回调。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### isSceneAssetsDownloaded [#issceneassetsdownloaded-1] ```objc - (NSInteger)isSceneAssetsDownloaded:(NSInteger)sceneId; ``` 判断本地是否已经下载指定场景。 x **参数** `sceneId`:场景的 ID,可以从 [`AgoraMetaSceneInfo`](#agorametaceneinfo) 获取。 **返回值** - 0:未下载到本地。 - 1:已下载到本地。 ### downloadSceneAssets [#downloadsceneassets-1] ```objc - (NSInteger)downloadSceneAssets:(NSInteger)sceneId; ``` 下载场景资源到本地。 调用该方法会触发 `AgoraMetaEventDelegate` 协议的 `onDownloadSceneAssetsProgress` 回调。 **参数** `sceneId`:场景的 ID,可以从 [`AgoraMetaSceneInfo`](#agorametaceneinfo) 获取。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### cancelDownloadSceneAssets [#canceldownloadsceneassets-1] ```objc - (NSInteger)cancelDownloadSceneAssets:(NSInteger)sceneId; ``` 取消下载场景到本地。 调用该方法会触发 `AgoraMetaEventDelegate` 协议的 `onDownloadSceneAssetsProgress` 回调,其中 `state` 为 `3(Failed)`。 调用该方法后如果再次调用 `downloadSceneAssets`,会从上次取消下载时的进度恢复下载。 **参数** `sceneId`:场景的 ID,可以从 [`AgoraMetaSceneInfo`](#agorametaceneinfo) 获取。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### cleanSceneAssets [#cleansceneassets-1] ```objc - (NSInteger)cleanSceneAssets:(NSInteger)sceneId; ``` 清理本地场景资源。 **参数** `sceneId`:场景的 ID,可以从 [`AgoraMetaSceneInfo`](#agorametaceneinfo) 获取。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### createScene [#createscene-1] ```objc - (NSInteger)createScene:(AgoraMetaSceneConfig *_Nonnull)config; ``` 创建 `AgoraMetaScene` 对象。 调用该方法会触发 `AgoraMetaEventDelegate` 协议的 [`onCreateSceneResult`](#oncreatesceneresult) 回调。成功创建的 `AgoraMetaScene` 对象可以在该回调里拿到。 **注意** - 如果你在创建场景时想开启面部捕捉,你可以通过 `config` 中的 `enableFaceCapture` 属性设置。 - 如果你在创建场景时不想开启面部捕捉,但是在后续流程中想开启面部捕捉,你可以调用 [`enableFaceCapture`](#enablefacecapture)。 **参数** `config`:创建 `AgoraMetaScene` 对象需要的配置信息,详见 [`AgoraMetaSceneConfig`](#agorametasceneconfig)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ## AgoraMetaScene [#agorametascene] 场景相关操作。 ### destroy [#destroy-2] 销毁 `AgoraMetaScene` 对象。 ```objc - (NSInteger)destroy; ``` **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### getLocalUserAvatar [#getlocaluseravatar-1] ```objc - (AgoraMetaLocalUserAvatar *_Nullable)getLocalUserAvatar; ``` 进入场景前,可以调用该方法获取用户的昵称、虚拟形象、装扮捏脸等信息。 **返回值** `AgoraMetaLocalUserAvatar` 对象。 ### createRenderView [#createrenderview] ```objc - (UIView *_Nullable)createRenderView:(CGRect)frame; ``` 创建场景渲染所需的视图。 **参数** - `frame`:视图的位置和大小。 **返回值** 创建的视图对象。 ### enterScene [#enterscene-1] ```objc - (NSInteger)enterScene:(AgoraMetaEnterSceneConfig *_Nonnull)config; ``` 进入场景。 成功调用该方法会触发 `AgoraMetaSceneEventDelegate` 协议的 [`onEnterSceneResult`](#onentersceneresult) 回调。 **参数** `config`:进入场景所需要的配置信息,详见 [`AgoraMetaEnterSceneConfig`](#agorametaentersceneconfig)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### leaveScene [#leavescene-1] ```objc - (NSInteger)leaveScene; ``` 进入场景。 成功调用该方法会触发 `AgoraMetaSceneEventDelegate` 协议的 [`onLeaveSceneResult`](#onleavesceneresult) 回调。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### sendSceneMessage [#sendscenemessage-1] ```objc - (NSInteger)sendSceneMessage:(NSData *_Nonnull)message; ``` 往场景发送自定义消息。 该方法适用于 App 需要和 Unity 通信的场景资源。Unity 收到自定义消息后可以进行自定义的逻辑处理。 **注意** 该方法必须在 `enterScene` 之后调用。 **参数** `message`:自定义消息,目前只支持字符串。消息格式可以自定义。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### enableVideoDisplay [#enablevideodisplay-1] ```objc - (NSInteger)enableVideoDisplay:(NSString *_Nonnull)displayId enable:(BOOL)enable; ``` 开启/关闭场景里的视频显示器。 **参数** - `displayId`:指定显示器的 ID。该 ID 需要由你的 Native 开发人员和 Unity 开发人员协商后规定。 - `enable`:是否开启指定显示器: - `YES`:开启显示器,即开始视频渲染。 - `NO`:关闭显示器,即关闭视频渲染。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### pushVideoFrameToDisplay [#pushvideoframetodisplay-1] ```objc - (NSInteger)pushVideoFrameToDisplay:(NSString *_Nonnull)displayId frame:(AgoraVideoFrame *_Nullable)frame; ``` 往场景里的视频显示器推送原始视频帧。 **参数** - `displayId`:指定显示器的 ID。ID 需要由你的 Native 开发人员和 Unity 开发人员协商后规定。 - `frame`:视频帧。详见 RTC SDK API 参考中的 [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/ios/class-externalvideoframe)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### addSceneView [#addsceneview-1] ```objc - (NSInteger)addSceneView:(UIView *_Nonnull)view sceneDisplayConfig:(AgoraMetaSceneDisplayConfig *_Nullable)config; ``` 添加场景显示视图。 调用该方法在场景中添加一个视图,用于在频道内发布主播的 Avatar 形象。调用成功后,SDK 会触发 `AgoraMetaSceneEventDelegate` 协议的 [`onAddSceneViewResult`](#onaddsceneviewresult) 回调。 **参数** - `view`:视频视图。 - `config`:场景显示相关配置参数,[`AgoraMetaSceneDisplayConfig`](#agorametascenedisplayconfig)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### removeSceneView [#removesceneview-1] ```objc - (NSInteger)removeSceneView:(UIView *_Nonnull)view; ``` 移除场景显示视图。 调用成功后,SDK 会触发 `AgoraMetaSceneEventDelegate` 协议的 [`onRemoveSceneViewResult`](#onremovesceneviewresult) 回调。 **参数** `view`:待移除的视图。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### enableFaceCapture [#enablefacecapture] ```objc - (NSInteger)enableFaceCapture:(BOOL)enable; ``` 开启或关闭面部捕捉。 **注意** 如果你在调用 [`createScene`](#createscene) 创建场景时不想开启面部捕捉,但是在后续流程中想开启面部捕捉,你可以调用本方法。 **参数** `enable`:是否开启面部捕捉: - `YES`:开启。 - `NO`:不开启。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### enableSceneVideoCapture [#enablescenevideocapture-1] ```objc - (NSInteger)enableSceneVideoCapture:(UIView *_Nonnull)view enable:(BOOL)enable; ``` 开启或关闭场景渲染画面捕获。 该方法用于开启或关闭场景渲染画面捕获。通过与 `AgoraRtcEngineKit` 的 [`joinChannelByToken` [1/2]](/zh-CN/api-reference/rtc/ios/channel#api_irtcengine_joinchannel1) 方法配合使用,可以将场景渲染的画面发布到 RTC 频道中。 **参数** - `view`:需要捕获的场景视图。 - `enable`:是否开启场景渲染画面捕获。 - `YES`:开启。场景画面会发布到 RTC 频道中。 - `NO`:(默认)不开启。场景画面不会发不到 RTC 频道中。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ## AgoraMetaLocalUserAvatar [#agorametalocaluseravatar] 包含在 `AgoraMetaScene` 中,生命周期和 `AgoraMetaScene` 相同。 ### setUserInfo [#setuserinfo-1] ```objc - (NSInteger)setUserInfo:(AgoraMetaUserInfo *_Nullable)userInfo; ``` 设置用户的基本信息。 **参数** `userInfo`:在场景内展示的用户信息,详见 [`AgoraMetaUserInfo`](#agorametauserinfo)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### getUserInfo [#getuserinfo-1] ```objc - (AgoraMetaUserInfo *_Nullable)getUserInfo; ``` 获取用户的基本信息。 **返回值** [`AgoraMetaUserInfo`](#agorametauserinfo) 对象。 ### setModelInfo [#setmodelinfo-1] ```objc - (NSInteger)setModelInfo:(AgoraMetaAvatarModelInfo *_Nullable)modelInfo; ``` 设置用户的模型信息。 **参数** `modelInfo`:用户的虚拟形象模型信息,详见 [`AgoraMetaAvatarModelInfo`](#agorametaavatarmodelinfo)。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### getModelInfo [#getmodelinfo-1] ```objc - (AgoraMetaAvatarModelInfo *_Nullable)getModelInfo; ``` 获取当前使用的用户模型信息。 **返回值** [`AgoraMetaAvatarModelInfo`](#agorametaavatarmodelinfo) 对象。 ### setExtraInfo [#setextrainfo-1] ```objc - (NSInteger)setExtraInfo:(NSData *_Nullable)customInfo; ``` 设置自定义的用户信息。 你可以通过该方法设置用户的装扮信息、捏脸信息。 **参数** `customInfo`:自定义的用户信息。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ### getExtraInfo [#getextrainfo-1] ```objc - (NSData *_Nullable)getExtraInfo; ``` 获取自定义的用户信息。 **返回值** 当前使用的自定义的用户信息。 ### applyInfo [#applyinfo-1] ```objc - (NSInteger)applyInfo; ``` 应用新设置的用户信息。 **注意** - 如果你在进入场景资源前调用 `setUserInfo`、`setModelInfo`、`setExtraInfo` 方法,则不需要调用 `applyInfo`。 - 如果你在进入场景资源后调用了 `setUserInfo`、`setModelInfo`、`setExtraInfo` 方法,必须再调用 `applyInfo` 让设置的信息生效。 **返回值** - 0:方法调用成功 - < 0:方法调用失败 ## AgoraMetaEventDelegate [#agorametaeventdelegate] `AgoraMetaServiceKit` 接口的异步方法的事件回调协议。 ### onCreateSceneResult [#oncreatesceneresult-1] ```objc - (void)onCreateSceneResult:(AgoraMetaScene *_Nullable)scene errorCode:(NSInteger)errorCode; ``` `AgoraMetaScene` 创建回调。 **参数** - `scene`:创建的 `AgoraMetaScene` 对象,用于后续进出场景等操作。 - `errorCode`:错误码: - 0 表示创建成功。 - 其余情况表示创建失败。 ### onConnectionStateChanged [#onconnectionstatechanged-1] ```objc - (void)onConnectionStateChanged:(AgoraMetaConnectionStateType)state reason:(AgoraMetaConnectionChangedReasonType)reason; ``` 连接状态改变回调。 **参数** - `state`:连接状态。 - `1`:断开连接。 - `2`:正在连接。 - `3`:连接成功。 - `4`:正在重连。 - `5`:连接丢弃。 - `reason`:连接状态改变的原因。 ### onTokenWillExpire [#ontokenwillexpire-1] ```objc - (void)onTokenWillExpire; ``` Token 即将过期回调。 收到该回调后,你需要在服务器生成新的 Token,然后调用 [`renewToken`](#renewtoken) 并在参数里传入新 Token。 ### onGetSceneAssetsInfoResult [#ongetsceneassetsinforesult-1] ```objc - (void)onGetSceneAssetsInfoResult:(NSMutableArray * _Nonnull)sceneInfos errorCode:(NSInteger)errorCode; ``` 获取场景资源列表回调。 **参数** - `metaSceneAssetsInfo`:场景资源信息列表,详见 [`AgoraMetaSceneInfo`](#agormetasceneinfo)。 - `errorCode`:错误码: - 0 表示获取列表成功。 - 其余情况表示获取列表失败。 ### onDownloadSceneAssetsProgress [#ondownloadsceneassetsprogress-1] ```objc - (void)onDownloadSceneAssetsProgress:(NSInteger)sceneId progress:(NSInteger)progress state:(AgoraMetaDownloadStateType)state; ``` 下载场景资源进度回调。 **参数** - `sceneId`:场景资源 ID。 - `progress`:下载进度,取值范围 [0,100]。 - `state`:下载状态: - `0`:空闲。 - `1`:正在下载。 - `2`:下载完成。 - `3`:下载失败 ## AgoraMetaSceneEventDelegate [#agorametasceneeventdelegate] `AgoraMetaScene` 接口的异步方法的事件回调协议。 ### onEnterSceneResult [#onentersceneresult-1] ```objc - (void)metaScene:(AgoraMetaScene *_Nonnull)scene onEnterSceneResult:(NSInteger)errorCode; ``` 进入场景的结果回调。 **参数** `errorCode`:错误码: - 0 表示进入场景成功。 - 其余情况进入场景失败。 ### onLeaveSceneResult [#onleavesceneresult-1] ```objc - (void)metaScene:(AgoraMetaScene *_Nonnull)scene onLeaveSceneResult:(NSInteger)errorCode; ``` 离开场景的结果回调。 **参数** `errorCode`:错误码: - 0 表示离开场景成功。 - 其余情况离开场景失败。 ### onSceneMessageReceived [#onscenemessagereceived-1] ```objc - (void)metaScene:(AgoraMetaScene *_Nonnull)scene onSceneMessageReceived:(NSData * _Nonnull)message; ``` 接收场景信息回调。 App 收到 Unity 场景发送的自定义信息时,SDK 会触发该回调。 **参数** `message`:自定义格式的消息。目前只支持字符串。 ### onUserPositionChanged [#onuserpositionchanged-1] ```objc - (void)metaScene:(AgoraMetaScene *_Nonnull)scene onUserPositionChanged:(NSString * _Nonnull)uid posInfo:(AgoraMetaPositionInfo * _Nonnull)posInfo; ``` 本地或远端用户位置变化回调。 用户位置变化时,SDK 会触发该回调。 **参数** - `uid`:本地或远端用户的用户 ID。 - `posInfo`:用户的位置信息,详见 [`AgoraMetaPositionInfo`](#agorametapositioninfo)。 ### onReleasedScene [#onreleasedscene-1] ```objc - (void)metaScene:(AgoraMetaScene *_Nonnull)scene onReleasedScene:(NSInteger)errorCode; ``` `AgoraMetaScene` 释放回调。 **参数** `status`:错误码: - 0 表示释放 `AgoraMetaScene` 成功。 - 其余情况释放 `AgoraMetaScene` 失败。 ### onAddSceneViewResult [#onaddsceneviewresult-1] ```objc - (void)metaScene:(AgoraMetaScene *_Nonnull)scene onAddSceneViewResult:(UIView * _Nonnull)view errorCode:(NSInteger)errorCode; ``` 添加场景显示视图回调。 调用 `AgoraMetaScene` 类的 [`addSceneView`](#addsceneview) 方法添加场景显示视图后,SDK 会触发该回调。 **参数** - `view`:视频视图。 - `errorCode`:错误码: - 0 表示添加视图成功。 - 其余情况添加视图失败。 ### onRemoveSceneViewResult [#onremovesceneviewresult-1] ```objc - (void)metaScene:(AgoraMetaScene *_Nonnull)scene onRemoveSceneViewResult:(UIView * _Nonnull)view errorCode:(NSInteger)errorCode; ``` 移除场景显示视图回调。 调用 `AgoraMetaScene` 类的 [`removeSceneView`](#removesceneview) 方法移除场景显示视图后,SDK 会触发该回调。 **参数** - `view`:视频视图。 - `errorCode`:错误码: - 0 表示移除视图成功。 - 其余情况移除视图失败。 ## 类型定义 [#类型定义-1] ### AgoraMetaServiceConfig [#agorametaserviceconfig] 初始化 `AgoraMetaServiceKit` 的配置信息。 ```objc __attribute__((visibility("default"))) @interface AgoraMetaServiceConfig : NSObject @property (nonatomic, copy) NSString * _Nonnull appId; @property (nonatomic, copy) NSString * _Nonnull rtmToken; @property (nonatomic, copy) NSString * _Nonnull userId; @property (nonatomic, weak) id _Nullable delegate; @property (nonatomic, copy) NSString * _Nonnull localDownloadPath; @property (nonatomic, assign) AgoraRtcEngineKit* _Nullable rtcEngine; @end ``` - `appId`:在声网控制台获取的 App ID。 - `rtmToken` :用于登录声网 RTM 系统的动态密钥。开启动态鉴权后可用。 - `userId`:登录声网 RTM 系统的用户 ID。该字符串不可超过 64 字节。可以通过以下方式和声网 RTC 用户 ID 绑定: - (推荐)使用 Int 型的 RTC 用户 ID,RTM 用户 ID 设为相同的数字字符串。 - 使用 String 型的 RTC 用户 ID,RTM 用户 ID 设为相同的字符串。 - 使用 Int 型的 RTC 用户 ID,RTM 用户 ID 设为不同的数字字符串,并且自行维护二者的映射关系。 - `delegate`:回调事件,详见 [`AgoraMetaEventDelegate`](#agorametaeventdelegate)。 - `localDownloadPath` :场景资源下载到本地的保存路径。 - `rtcEngine`:`AgoraRtcEngineKit` 实例,创建方法详见 [`sharedEngineWithConfig`](/zh-CN/api-reference/rtc/ios/initialize#api_irtcengine_initialize)。 ### AgoraMetaUserInfo [#agorametauserinfo] 用户信息。 ```objc __attribute__((visibility("default"))) @interface AgoraMetaUserInfo : NSObject @property (nonatomic, copy) NSString * _Nonnull userId; @property (nonatomic, copy) NSString * _Nonnull userName; @property (nonatomic, copy) NSString * _Nonnull userIconUrl; @end ``` - `userId`:登录声网 RTM 系统的用户 ID。该字符串不可超过 64 字节。可以通过以下方式和声网 RTC 用户 ID 绑定: - (推荐)使用 Int 型的 RTC 用户 ID,RTM 用户 ID 设为相同的数字字符串。 - 使用 String 型的 RTC 用户 ID,RTM 用户 ID 设为相同的字符串。 - 使用 Int 型的 RTC 用户 ID,RTM 用户 ID 设为不同的数字字符串,并且自行维护二者的映射关系。 - `userName`:用户昵称,用于在场景里显示用户昵称。 - `userIconUrl`:用户头像的 URL,用于在场景里显示用户头像。 ### AgoraMetaSceneInfo [#agorametasceneinfo] 场景资源信息。 ```objc __attribute__((visibility("default"))) @interface AgoraMetaSceneInfo : NSObject @property (nonatomic, assign) NSInteger sceneId; @property (nonatomic, copy) NSString * _Nonnull sceneName; @property (nonatomic, copy) NSString * _Nonnull thumbnailPath; @property (nonatomic, copy) NSString * _Nonnull scenePath; @property (nonatomic, copy) NSString * _Nonnull parentScenePath; @property (nonatomic, copy) NSString * _Nonnull desc; @property (nonatomic, copy) NSString * _Nonnull sceneConfig; @property (nonatomic, copy) NSString * _Nullable extraInfo; @property (nonatomic, copy) NSString * _Nonnull sceneVersion; @property (nonatomic, copy) NSString * _Nonnull sceneLocalVersion; @property (nonatomic, assign) NSInteger totalSize; @property (nonatomic, strong) NSArray * _Nonnull bundles; @end ``` - `sceneId`:场景的唯一标识符。 - `sceneName`:场景名称。 - `thumbnailPath`:场景缩略图的本地路径。 - `scenePath`:场景资源的本地路径。 - `parentScenePath`:依赖的父场景资源的本地路径。 - `desc`:场景的描述文字。 - `sceneConfig`:场景的配置信息。 - `extraInfo`:其它额外信息。 - `bundles`:场景支持的资源包列表。 - `sceneVersion`:场景资源在服务器上的版本号。 - `sceneLocalVersion`:场景资源在本地的版本号。 - `totalSize`:场景资源包总大小。 ### AgoraMetaBundleInfo [#agorametabundleinfo] 资源包信息。 ```objc __attribute__((visibility("default"))) @interface AgoraMetaBundleInfo : NSObject @property (nonatomic, assign) NSInteger bundleId; @property (nonatomic, assign) NSInteger sceneId; @property (nonatomic, assign) AgoraMetaBundleType bundleType; @property (nonatomic, copy) NSString * _Nonnull bundleCode; @property (nonatomic, copy) NSString * _Nonnull bundleName; @property (nonatomic, copy) NSString * _Nonnull desc; @property (nonatomic, copy) NSString * _Nonnull bundlePath; @property (nonatomic, copy) NSString * _Nonnull thumbnailPath; @property (nonatomic, copy) NSString * _Nonnull assets; @property (nonatomic, copy) NSString * _Nullable extraInfo; @property (nonatomic, assign) NSInteger bundleSize; @end ``` - `bundleId`:资源包 ID。不同平台(Android、iOS)的同一个资源包的 ID 是不同的。 - `sceneId`:所属的场景资源 ID。 - `bundleType`:资源包类型: - `1`:场景资源。 - `2`:虚拟形象(avatar)资源。 - `3`:assetManifest 资源。 - `100`:其他资源。 - `bundleCode`:资源包代码,不同平台(Android、iOS)同一个资源包的代码要保持一致。 - `bundleName`:资源包名称。 - `desc`:资源包描述。 - `bundlePath`:资源包的本地存储路径。 - `thumbnailPath`:资源包缩略图的本地存储路径。 - `assets`:预留参数。 - `extraInfo`:资源包的其它额外信息。 - `bundleSize`:资源包大小。 ### AgoraMetaSceneConfig [#agorametasceneconfig] 场景的配置信息。 ```objc __attribute__((visibility("default"))) @interface AgoraMetaSceneConfig : NSObject @property (nonatomic, assign) AgoraMetaStateSyncMode syncMode; @property (nonatomic, weak) id _Nullable delegate; @property (nonatomic, assign) BOOL enableFaceCapture; @property (nonatomic, copy) NSString * _Nonnull faceCaptureAppId; @property (nonatomic, copy) NSString * _Nonnull faceCaptureCertificate; @end ``` - `syncMode`:消息同步模式: - `AgoraMetaStateSyncModeNone(0)`:不同步消息。 - `AgoraMetaStateSyncModeNormal(1)`:(默认)通过 RTM 同步消息。 - `delegate`:`AgoraMetaSceneEventDelegate` 事件回调协议。 - `enableFaceCapture`:是否开启面部捕捉: - `YES`:开启。 - `NO`:(默认)不开启。 - `faceCaptureAppId`:开启面部捕捉时设置的 App ID。开启面捕时必填。 - `faceCaptureCertificate`:开启面部捕捉时设置的 Certificate(证书)。开启面捕时必填。 通过面捕 App ID 和 Certificate 可以获取对应的面捕证书 (license)。开启面捕功能时,需要你设置面捕证书 (license)。 ### AgoraMetaEnterSceneConfig [#agorametaentersceneconfig] 进入场景的配置信息。 ```objc __attribute__((visibility("default"))) @interface AgoraMetaEnterSceneConfig : NSObject @property (nonatomic, copy) NSString * _Nonnull roomName; @property (nonatomic, strong) UIView * _Nonnull sceneView; @property (nonatomic, assign) NSInteger sceneId; @property (nonatomic, copy) NSString * _Nullable scenePath; @property (nonatomic, strong) NSData * _Nullable extraInfo; @end ``` - `roomName`:进入场景的房间名称。 - `sceneView`:场景渲染所需要的视图。iOS 上需要用 `AgoraMetaScene` 类的的 `createRenderView` 方法创建。 - `sceneId`:进入场景的 ID。 - `scenePath`:(可选)`sceneId` 为 0 时,表示从本地路径加载资源,此时,`scenePath` 必须设为本地资源文件夹的路径。 - `extraInfo`:(可选)加载场景资源时需要的其它额外自定义信息。你可以自行定义,目前只支持字符串。 ### AgoraMetaAvatarModelInfo [#agorametaavatarmodelinfo] 用户的虚拟形象 (Avatar) 信息。 ```objc __attribute__((visibility("default"))) @interface AgoraMetaAvatarModelInfo : NSObject @property (nonatomic, copy) NSString * _Nonnull bundleCode; @property (nonatomic,assign) BOOL localVisible; @property (nonatomic,assign) BOOL remoteVisible; @property (nonatomic,assign) BOOL syncPosition; @end ``` - `bundleCode`:人物模型所在的资源包代码。 - `localVisible`:虚拟人物模型是否在本地可见。如果设为 `NO`,`remoteVisible` 和 `syncPosition` 会自动设为 `NO`,并且无法更改。 - `remoteVisible`:虚拟人物模型是否在远端可见。 - `syncPosition`:是否同步本地人物渲染时所需要的信息(例如模型、装扮、捏脸信息等),用于控制玩家和游客模式。如果设为 `NO`,`remoteVisible` 不生效。 ### AgoraMetaPositionInfo [#agorametapositioninfo] 用户的位置信息。 ```objc __attribute__((visibility("default"))) @interface AgoraMetaPositionInfo : NSObject @property (nonatomic, copy) NSArray * _Nonnull position; @property (nonatomic, copy) NSArray * _Nonnull forward; @property (nonatomic, copy) NSArray * _Nonnull right; @property (nonatomic, copy) NSArray * _Nonnull up; @end ``` - `position`:用户的坐标位置。 - `forward`:用户朝向的三维向量。 - `right`:用户右手方向的向量。 - `up`:用户头朝向的向量。 ### AgoraMetaSceneDisplayConfig [#agorametascenedisplayconfig] 场景显示相关配置。 ```objc __attribute__((visibility("default"))) @interface AgoraMetaSceneDisplayConfig : NSObject @property (nonatomic, assign) NSInteger width; @property (nonatomic, assign) NSInteger height; @property (nonatomic, strong) NSData * _Nullable extraInfo; @end ``` - `width`:场景渲染画面的宽。 - `height`:场景渲染画面的高度。该宽高决定拿到场景渲染画面的原始视频帧的大小。如果要将画面发布到 RTC 频道中,建议将该宽高设置为与 RTC 的视频编码参数宽高一致,以避免缩放裁剪导致的性能损耗。 - `extraInfo`:Unity 渲染场景所需的额外信息,该字段是用户自定义的,一般由你的 Native 开发人员和 Unity 开发人员约定好。 <_PlatformProcessedMarker close="true" />