NIMClient.java

浏览该文件的文档.

package com.netease.nimlib.sdk;

import android.app.Application;
import android.content.Context;
import android.util.Log;
import com.netease.nimlib.BuildConfig;
import com.netease.nimlib.SDKCache;
import com.netease.nimlib.SDKState;
import com.netease.nimlib.common.infra.Handlers;
import com.netease.nimlib.invocation.sync.base.APISyncHelper;
import com.netease.nimlib.log.model.LogDesensitizationConfigHelper;
import com.netease.nimlib.report.ApiTraceEventManager;
import com.netease.nimlib.sdk.auth.LoginInfo;
import com.netease.nimlib.sdk.msg.model.CaptureDeviceInfoConfig;
import com.netease.nimlib.sdk.util.NIMUtil;
import com.netease.nimlib.sdk.util.api.RequestResult;
import com.netease.nimlib.util.storage.NimStorageUtil;

/**
 * SDK 核心接口类，用于初始化 SDK，获取各个服务能力接口，获取当前状态等功能。
 */
public class NIMClient {

    public static final String TAG = "NIMClient";
    /**
     * [初始化 SDK 方式一] 在 {@link Application#onCreate()} 中调用该方法在应用启动时初始化 SDK。
     *
     * @par 使用场景：
     * 属于常规初始化方式，适用绝大多数的初始化场景。
     * @par 使用建议：
     * 建议在 {@link Application#onCreate()} 中添加进程判断，SDK 的初始化方法必须在主进程中调用。不要把业务逻辑写入 core 进程，理论上，core 进程的 {@link Application#onCreate()}（或者 Application 的其他方法）只能做与 NIM SDK 相关的工作。IM 进程启动时也不要初始化第三方库。
     * @par 调用时机：
     * 请确保在调用其他 API 前先调用该方法初始化 SDK。
     * @par 参数说明：
     * <table>
     * <tr>
     * <th>参数名称</th>
     * <th>描述</th>
     * </tr>
     * <tr>
     * <td>context</td>
     * <td>调用上下文</td>
     * </tr>
     * <tr>
     * <td>info</td>
     * <td>手动登录成功的用户信息。如 account（即 accid）和 token<ul><li>如果提供，SDK 在初始化的同时将自动调用登录接口进行登录（同时将打开用户相关的数据库）</li><li>如果当前还没有登录成功的用户，传入 null，后续可以手动调用 {@link com.netease.nimlib.sdk.auth.AuthService#login(LoginInfo)} 方法进行登录</li></ul></td>
     * </tr>
     * <tr>
     * <td>options</td>
     * <td>SDK 的其他初始化配置。如 App Key、第三方离线推送配置、是否开启会话已读多端同步等<ul><li>其中 App Key 如果已在集成 SDK 时（AndroidManifest.xml 中通过 meta-data 的方式设置）传入，则此处不需要再传入，<strong>否则必须传入</strong>，如果两处都设置了，取此处的值</li><li>如果返回值为 null，则全部使用默认参数</li></ul></td>
     * </tr>
     * </table>
     * @par 相关回调：
     * {@link com.netease.nimlib.sdk.lifecycle.SdkLifecycleObserver#observeMainProcessInitCompleteResult(Observer, boolean)} ：初始化进程回调
     *
     */
    public static void init(Context context, LoginInfo info, SDKOptions options) {
        final long startTime = System.currentTimeMillis();
        if (LogDesensitizationConfigHelper.printToLogcat(options)) {
            Log.i(TAG, "NIMClient init");
        }
        SDKCache.config(context, info, options);

        // 老的初始化接口，需要判断进程
        if (NIMUtil.isMainProcess(context)) {
            SDKCache.initUI();
            Handlers.sharedInstance().newMiscHandler().post(() -> {
                ApiTraceEventManager.getInstance().recordPendingTrackEvent(startTime,"NIMClient","init");
            });
        }
    }

    /**
     * [初始化 SDK 方式二] 在 {@link Application#onCreate()} 中配置 SDK（仅仅是配置，不影响性能），具体可配置的参数同 {@link NIMClient#init(Context, LoginInfo, SDKOptions)}。
     *
     * @par 使用场景：
     * 适用于需要用户授权隐私信息采集的业务场景。与常规初始化 SDK 方式相比，该方式耗时更少，且更适配弱 IM 场景（应用仅需在其部分业务中使用 IM 能力（不需要在应用启动时就做 IM 自动登录），且并不需要保证消息、通知和数据的实时性的场景）。
     * @par 使用建议：
     * 该初始化方式一般不再需要做进程判断。
     * @par 使用限制：
     * 该接口适用的 SDK 版本：v5.0.0及以上。<br>
     * {@link NIMClient#config(Context, LoginInfo, SDKOptions)} 方法必须与 {@link NIMClient#initSDK()} 方法搭配使用，在应用代码的任意位置初始化 SDK。
     * @par 参数说明：
     * <table>
     * <tr>
     * <th>参数名称</th>
     * <th>描述</th>
     * </tr>
     * <tr>
     * <td>context</td>
     * <td>调用上下文</td>
     * </tr>
     * <tr>
     * <td>info</td>
     * <td>手动登录成功的用户信息。如 account（即 accid）和 token<ul><li>如果提供，SDK 在初始化的同时将自动调用登录接口进行登录（同时将打开用户相关的数据库）</li><li>如果当前还没有登录成功的用户，传入 null，后续可以手动调用 {@link com.netease.nimlib.sdk.auth.AuthService#login(LoginInfo)} 方法进行登录</li></ul></td>
     * </tr>
     * <tr>
     * <td>options</td>
     * <td>SDK 的其他初始化配置。如 App Key、第三方离线推送配置、是否开启会话已读多端同步等<ul><li>其中 App Key 如果已在集成 SDK 时（AndroidManifest.xml 中通过 meta-data 的方式设置）传入，则此处不需要再传入，<strong>否则必须传入</strong>，如果两处都设置了，取此处的值</li><li>如果返回值为 null，则全部使用默认参数</li><li>可通过 {@link SDKOptions#asyncInitSDK} 参数配置进行同步/异步初始化</li><li>可通过 {@link SDKOptions#reducedIM} 参数实现支持弱 IM 模式，延迟加载 push 进程服务等<strong>（非弱 IM 场景慎用）</strong></li></ul></td>
     * </tr>
     * </table>
     *
     */
    public static void config(Context context, LoginInfo info, SDKOptions options) {
        final long startTime = System.currentTimeMillis();
        if (LogDesensitizationConfigHelper.printToLogcat(options)) {
            Log.i(TAG, "NIMClient config");
        }
        SDKCache.config(context, info, options);

        //config时马上设置主进程标志位，防止LocalAgent构造时return导致空指针
        if (NIMUtil.isMainProcessPure(context) > 0) {
            SDKState.setProcessTag(2);
            Handlers.sharedInstance().newMiscHandler().post(() -> {
                ApiTraceEventManager.getInstance().recordPendingTrackEvent(startTime,"NIMClient","config");
            });
        }
    }

    /**
     * [初始化 SDK 方式二] 在 UI 进程主线程上按需初始化 SDK（不放在 {@link Application#onCreate()} 中初始化）。与 {@link NIMClient#config(Context, LoginInfo, SDKOptions)} 方法搭配使用。
     *
     * @par 使用场景：
     * 适用于需要用户授权隐私信息采集的业务场景。与常规初始化 SDK 方式相比，该方式耗时更少，且更适配弱 IM 场景（应用仅需在其部分业务中使用 IM 能力（不需要在应用启动时就做 IM 自动登录），且并不需要保证消息、通知和数据的实时性的场景）。
     * @par 使用建议：
     * 该初始化方式一般不再需要做进程判断。
     * @par 使用限制：
     * 该接口适用的 SDK 版本：v5.0.0及以上。<br>
     * 该方法需要与 {@link NIMClient#config(Context, LoginInfo, SDKOptions)} 方法搭配使用，即先在 Application#onCreate 中调用 config 方法，然后在应用代码的任意位置调用 {@link NIMClient#initSDK()} 方法初始化 SDK。
     *
     */
    public static void initSDK() {
        long startTime = System.currentTimeMillis();
        if (LogDesensitizationConfigHelper.printToLogcat()) {
            Log.i(TAG, "NIMClient initSDK");
        }
        SDKCache.initUI();
        if (NIMUtil.isMainProcess(SDKCache.getContext())) {
            Handlers.sharedInstance().newMiscHandler().post(() -> {
                ApiTraceEventManager.getInstance().recordPendingTrackEvent(startTime,"NIMClient","initSDK");
            });
        }

    }

    /**
     * [初始化 SDK 方式三] 在 UI 进程主线程上按需初始化 SDK（不一定放在 {@link Application#onCreate()} 中初始化）。
     *
     * @par 使用建议：
     * 除特殊需求，不建议使用该方式进行初始化 SDK。
     * @par 使用限制：
     * 该接口适用的 SDK 版本：v 及以上。
     * @par 参数说明：
     * <table>
     * <tr>
     * <th>参数名称</th>
     * <th>描述</th>
     * </tr>
     * <tr>
     * <td>context</td>
     * <td>调用上下文</td>
     * </tr>
     * <tr>
     * <td>info</td>
     * <td>手动登录成功的用户信息。如 account（即 accid）和 token<ul><li>如果提供，SDK 在初始化的同时将自动调用登录接口进行登录（同时将打开用户相关的数据库）</li><li>如果当前还没有登录成功的用户，传入 null，后续可以手动调用 {@link com.netease.nimlib.sdk.auth.AuthService#login(LoginInfo)} 方法进行登录</li></ul></td>
     * </tr>
     * <tr>
     * <td>options</td>
     * <td>SDK 的其他初始化配置。如 App Key、第三方离线推送配置、是否开启会话已读多端同步等<ul><li>其中 App Key 如果已在集成 SDK 时（AndroidManifest.xml 中通过 meta-data 的方式设置）传入，则此处不需要再传入，<strong>否则必须传入</strong>，如果两处都设置了，取此处的值</li><li>如果返回值为 null，则全部使用默认参数</li><li>可通过 {@link SDKOptions#asyncInitSDK} 参数配置进行同步/异步初始化</li><li>可通过 {@link SDKOptions#reducedIM} 参数实现支持弱 IM 模式，延迟加载 push 进程服务等<strong>（非弱 IM 场景慎用）</strong></li></ul></td>
     * </tr>
     * </table>
     *
     */
    public static void initDelay(Context context, LoginInfo info, SDKOptions options) {
        long startTime = System.currentTimeMillis();
        if (LogDesensitizationConfigHelper.printToLogcat(options)) {
            Log.i(TAG, "NIMClient initDelay");
        }

        // 老的初始化接口，需要判断进程
        if (NIMUtil.isMainProcess(context)) {
            SDKCache.config(context, info, options, true);
            SDKCache.initUI();
            Handlers.sharedInstance().newMiscHandler().post(() -> {
                ApiTraceEventManager.getInstance().recordPendingTrackEvent(startTime,"NIMClient","initDelay");
            });
        }
    }

    /**
     * 获取云信各服务接口。
     *
     * @par 调用时机：
     * 调用 NIM SDK 其他接口前，需要先调用该接口。
     * @par 参数说明：
     * <table>
     * <tr>
     * <th>参数名称</th>
     * <th>描述</th>
     * </tr>
     * <tr>
     * <td>clazz</td>
     * <td>服务接口类型实例</td>
     * </tr>
     * <tr>
     * <td><T></td>
     * <td>服务接口类型</td>
     * </tr>
     * </table>
     * @par 返回：
     * 服务接口
     *
     */
    public static <T> T getService(Class<T> clazz) {
        return SDKCache.getService(clazz);
    }

    /**
     * 在非 UI 线程中调用云信 SDK 异步 API，强制将异步调用转换为同步调用。
     * @par 使用场景：
     * 需要在没有 Looper 的非 UI 线程上同步调用云信 API，但是对应的接口云信没有同步版本，只有异步版本。例如，启动一个线程或者线程池处理云信 SDK 数据。
     * @par 使用建议：
     * 如果 SDK 提供了对应的同步API，请不要使用该方法强制转换一个异步 API。<br>
     * 该方法将阻塞调用者线程，直到异步 API 有结果响应。因此，除特殊场景不建议使用！
     * @par 使用限制：
     * 不允许在 UI 线程上或者带 Looper 的非 UI 线程上使用该异步到同步的强制转换（不符合 Android规范）！否则结果会返回错误码 {@link ResponseCode#RES_API_SYNC_RUN_ON_LOOPER_THREAD_EXCEPTION}。
     * @par 注意事项：
     * 带 Looper 的非 UI 线程调用云信异步 API，会在调用线程执行回调（4.4.0 版本之前的 SDK 版本，会统一回调到 UI 线程上）。
     * @par 参数说明：
     * <table>
     * <tr>
     * <th>参数名称</th>
     * <th>描述</th>
     * </tr>
     * <tr>
     * <td>future</td>
     * <td>异步 API 调用返回的回调</td>
     * </tr>
     * <tr>
     * <td><T></td>
     * <td>结果的数据类型</td>
     * </tr>
     * <tr>
     * <td>time</td>
     * <td>最大同步等待时间，单位毫秒，一般设置为 30000，超时后该方法直接返回错误，错误码参见 {@link ResponseCode#RES_API_SYNC_TIMEOUT}</td>
     * </tr>
     * </table>
     * @par 返回：
     * 在非 UI 线程上同步等待异步调用结果
     *
     */
    public static <T> RequestResult<T> syncRequest(InvocationFuture<T> future, long time) {
        return APISyncHelper.syncRequest(future, time);
    }

    /**
     * 在非 UI 线程调用云信 SDK 异步 API，强制将异步调用转换为同步调用。该接口已废弃，请使用 {@link NIMClient#syncRequest(InvocationFuture, long)} 接口。
     * @par 参数说明：
     * <table>
     * <tr>
     * <th>参数名称</th>
     * <th>描述</th>
     * </tr>
     * <tr>
     * <td>future</td>
     * <td>异步 API 调用返回的回调</td>
     * </tr>
     * <tr>
     * <td><T></td>
     * <td>结果的数据类型</td>
     * </tr>
     * </table>
     * @par 返回：
     * 在非 UI 线程上同步等待异步调用结果
     *
     */
    public static <T> RequestResult<T> syncRequest(InvocationFuture<T> future) {
        return APISyncHelper.syncRequest(future, 30 * 1000L);
    }

    /**
     * 获取当前用户的 IM 账号（accid）。
     * @par 返回：
     * 当前用户的 IM 账号（accid）
     */
    public static String getCurrentAccount(){
        String account = SDKCache.getAccount();
        if(account == null){
            account = "";
        }
        return account;
    }

    /**
     * 获取当前应用的 AppKey。
     * @par 返回：
     * 当前应用的 AppKey
     */
    public static String getAppKey(){
        try {
            String appKey = SDKCache.getAppKey();
            if(appKey == null)
            {
                return "";
            }
            return appKey;
        } catch (Exception e) {
           return "";
        }
    }

    /**
     * 获取当前用户的状态。
     * @par 返回：
     * 当前用户的状态 {@link StatusCode}
     */
    public static StatusCode getStatus() {
        return SDKState.getStatus();
    }

    /**
     * 获取 SDK 当前的登录模式。
     *
     * @par 返回：
     * 当前的登录模式 {@link ModeCode}包括以下三种模式：<ul><li>INIT：初始状态 </li><li>IM：IM 登录模式（可以登录聊天室，但需要保持 IM 和聊天室连接）</li><li>CHAT_ROOM_INDEPENDENT：聊天室独立登录模式（不需要 IM 连接）</li></ul>
     */

    public static ModeCode getMode() {
        return SDKState.getMode();
    }

    /**
     * 通知栏消息提醒开关。
     * @par 调用限制：
     * 只有 {@link StatusBarNotificationConfig} 配置不为空时才有效。<br>
     * SDKOptions.StatusBarNotificationConfig 默认为 null，即 SDK 不提供通知栏提醒功能，由客户 APP自行实现。因此如需启用通知栏消息提醒功能，需要先设置初始化参数 StatusBarNotificationConfig。
     * @par 参数说明：
     * on ：开关，true 为开启，false 为关闭，默认开启
     */
    public static void toggleNotification(boolean on) {
        SDKCache.toggleNotification(on);
    }


    /**
     * 撤回消息需要通知栏提醒的开关。
     * @par 调用限制：
     *只有 StatusBarNotificationConfig 配置不为空且通知栏消息提醒（{@link NIMClient#toggleNotification(boolean)}）开启时才有效。
     * @par 参数说明：
     * on ：开关，true 为开启，false 为关闭，默认开启
     *
     */
    public static void toggleRevokeMessageNotification(boolean on) {
        SDKCache.toggleRevokeMessageNotification(on);
    }

    /**
     * 更新通知栏消息提醒配置，包括是否需要振动提醒、是否需要响铃提醒等。
     * @par 使用场景：
     * 若未在初始化（SDKOptions.StatusBarNotificationConfig）时设置通知栏消息的配置项，或者初始化时设置了，但是需要修改其配置项，可调用该接口实现通知栏消息提醒配置的更新。
     * @par 参数说明：
     * config 通知栏消息提醒的配置项，包括响铃提醒、振动提醒、免打扰设置等
     *
     */
    public static void updateStatusBarNotificationConfig(StatusBarNotificationConfig config) {
        SDKCache.updateStatusBarNotificationConfig(config);
    }

    /**
     * 更新系统文案。
     * @par 使用场景：
     * 当系统语言发生变化时，可以调用该接口更新文案配置，实现 SDK 对多语言的支持。也可以用于定制通知栏消息提醒的文案。
     * @par 注意事项：
     * 配置不能立即生效，所有文案均需要在下次使用时才会生效。
     * @par 参数说明：
     * strings  SDK 中用到的文案字符串定义，目前仅状态栏消息提醒处使用。如果您没有提供自定义值，只使用默认值
     */
    public static void updateStrings(NimStrings strings) {
        SDKCache.updateStrings(strings);
    }

    /**
     * 获取 SDK 数据缓存目录路径。
     * @par 调用时机：
     * 建议在初始化 SDK 之后调用。
     * @par 返回：
     * SDK 数据缓存目录路径（包含子目录，如日志文件 log、消息中的文件 file、消息中的原图 image、消息中的音频 audio、消息中的原视频 video、图片/视频消息中的缩略图 thumb 等）
     */
    public static String getSdkStorageDirPath() {
        return NimStorageUtil.getRootPath();
    }

    /**
     * 运行时获取当前 SDK 版本号。
     * @par 返回：
     * 当前 SDK 版本号，例如 "1.0.0"
     */
    public static String getSDKVersion() {
        return BuildConfig.VERSION_NAME;
    }


    /**
     * 更新 SDK NOS Token 场景配置。对于 SDK NOS Token，云信 SDK 有默认值 ，若用户不单独配置，则直接采用默认值。
     * @par 默认值对应场景：
     * <ul><li>NimNosSceneKeyConstant::NIM_DEFAULT_PROFILE：用户和群组资料（例如头像）的上传默认走该场景</li><li>NimNosSceneKeyConstant::NIM_DEFAULT_IM：私聊、群聊、聊天室发送图片、音频、视频、文件等动作默认走该场景</li><li>NimNosSceneKeyConstant::NIM_SYSTEM_NOS_SCENE：SDK 内部上传文件（例如日志）默认走该场景，并且对应的过期时间不允许修改</li></ul>
     * 默认场景对应的默认过期时间为 NEVER_EXPIRE（永不过期，资源一直存在于服务器），用户可以修改默认场景（除 NIM_SYSTEM_NOS_SCENE 场景）的过期时间。<br>
     * 同时用户可以新增自定义场景并指定对应的过期时间（sceneKey-> expireTimeByDay），目前最多增加 10 个场景。
     * @par 使用场景：
     * 如果用户发送消息或上传文件等动作，需要指定其他的场景（指定 NOS 服务网络），可以先新增自定义场景，后续只需要传入相应的 sceneKey 即可。
     * @par 使用建议：
     * 在配置时，强烈建议将相应的 sceneKey 常量化，以方便使用，具体请参考 {@link com.netease.nimlib.NimNosSceneKeyConstant}。
     * @par 参数说明：
     * config  NOS Token 场景配置
     * @par 相关接口：
     * <ul><li>{@link NosTokenSceneConfig#appendCustomScene(String, int)}：增加自定义场景</li><li>{@link NosTokenSceneConfig#updateDefaultProfileSceneExpireTime(int)}：更新默认场景（NIM_DEFAULT_PROFILE）的过期时间</li><li>{@link NosTokenSceneConfig#updateDefaultIMSceneExpireTime(int)}：更新默认场景（NIM_DEFAULT_IM）的过期时间</li></ul>
     *
     */
    public static void updateTokenSceneConfig(NosTokenSceneConfig config) {
        SDKCache.updateTokenSceneConfig(config);
    }

    /**
     * 更新获取设备信息的相关配置。包括配置是否获取产品型号、是否获取制造商信息、是否获取品牌信息，null 表示都可以获取，没有限制。
     * @par 注意事项：
     * 不获取设备信息可能会影响功能的使用，若需要设置为不获取设备信息，请联系云信技术支持。
     * @par 参数说明：
     * captureDeviceInfoConfig 设备信息获取配置，包括配置是否获取产品型号、是否获取制造商信息、是否获取品牌信息
     */
    public static void updateCaptureDeviceInfoOption(CaptureDeviceInfoConfig captureDeviceInfoConfig) {
        SDKCache.updateCaptureDeviceInfoOption(captureDeviceInfoConfig);
    }
}