saveImageToPhotosAlbum
保存图片到系统相册
该方法用于将 APP 本地图片文件保存到用户设备的系统相册中。通常用于游戏截图保存、分享海报保存、二维码保存、战绩图保存等场景。
SDK 会传入一个本地图片文件路径,APP 侧需要校验文件是否存在,并将该图片写入系统相册。保存完成后,通过 SUDOPStateHandle 将结果回传给 SDK。
方法声明
java
/**
* 保存图片到系统相册
*
* @param handle 用于向 SDK 返回处理结果的状态句柄
* @param params 请求参数
*/
void saveImageToPhotosAlbum(
SUDOPStateHandle handle,
SUDOPSaveImageToPhotosAlbumParams params
);参数说明
SUDOPSaveImageToPhotosAlbumParams
java
public class SUDOPSaveImageToPhotosAlbumParams {
/**
* 图片文件路径,可以是临时文件路径或永久文件路径(本地路径),不支持网络路径
*/
public String filePath;
}| 字段名 | 类型 | 说明 |
|---|---|---|
filePath | String | 图片文件路径,可以是临时文件路径或永久文件路径;必须是本地路径,不支持网络路径 |
返回说明
通过 SUDOPStateHandle 将保存结果返回给 SDK。
保存成功
保存成功时调用:
java
handle.success(dataJson);该接口成功时通常不需要返回业务数据,可以传 null 或空字符串:
java
handle.success(null);或:
java
handle.success("");保存失败
保存失败时调用:
java
handle.failure(retCode, retMsg);| 参数 | 类型 | 说明 |
|---|---|---|
retCode | int | 错误码,0 表示成功,非 0 表示失败 |
retMsg | String | 错误描述信息 |
示例:
java
handle.failure(-1, "The filePath does not exist.");运行行为
- 由 SDK 触发:当游戏或 SDK 需要将本地图片保存到系统相册时,会调用
saveImageToPhotosAlbum。 - APP 校验文件路径:APP 侧需要检查
params.filePath是否为空、文件是否存在,以及是否为本地文件路径。 - APP 写入系统相册:校验通过后,APP 将对应图片写入系统相册。
- 异步或同步回调:保存完成后,APP 需要通过
handle.success(...)或handle.failure(...)通知 SDK 保存结果。 - 权限处理:在部分 Android 版本中,保存到相册可能需要申请存储或媒体权限,APP 应自行处理权限申请和兼容逻辑。
代码示例
java
@Override
public void saveImageToPhotosAlbum(
SUDOPStateHandle handle,
SUDOPSaveImageToPhotosAlbumParams params
) {
File file;
if (params.filePath == null || !(file = new File(params.filePath)).exists()) {
handle.failure(-1, "The filePath does not exist.");
return;
}
boolean result = false;
try {
result = saveImageToGallery(context, file);
} catch (Exception e) {
handle.failure(-1, "saveImageToPhotsAlbum error:" + e);
return;
}
if (result) {
handle.success(null);
} else {
handle.failure(-1, "saveImageToPhotsAlbum fail");
}
}推荐实现流程
text
SDK 调用 saveImageToPhotosAlbum
↓
APP 校验 params.filePath
↓
判断文件是否存在
↓
检查或申请相册/媒体存储权限
↓
将图片保存到系统相册
↓
保存成功:handle.success(null)
保存失败:handle.failure(retCode, retMsg)常见失败场景
| 失败场景 | 建议处理 |
|---|---|
filePath 为空 | handle.failure(-1, "The filePath does not exist.") |
| 文件不存在 | handle.failure(-1, "The filePath does not exist.") |
| 传入网络图片地址 | 返回失败,不支持网络路径 |
| 文件不是有效图片 | 返回失败,并提示图片格式异常 |
| 无相册或媒体写入权限 | 申请权限,用户拒绝时返回失败 |
| 系统相册写入失败 | 返回失败,并附带具体错误信息 |
| 保存过程中发生异常 | 捕获异常并通过 handle.failure 返回 |
注意事项
- 必须回调:无论保存成功还是失败,都需要调用
handle.success(...)或handle.failure(...)。 - 只支持本地路径:
filePath必须是本地图片文件路径,不支持 HTTP/HTTPS 等网络路径。 - 文件存在性校验:保存前必须校验文件是否存在,避免无效路径导致异常。
- 权限兼容:不同 Android 版本的相册保存权限要求不同,APP 需要根据系统版本自行适配。
- Android 10 及以上:建议使用
MediaStore保存到相册,适配分区存储机制。 - Android 9 及以下:可能需要申请
WRITE_EXTERNAL_STORAGE权限。 - 避免阻塞主线程:图片复制、写入相册和媒体库刷新可能耗时,建议放到子线程执行。
- 错误信息准确:失败时建议返回明确的错误原因,便于 SDK 或业务侧定位问题。
- 方法名拼写:示例中的错误信息为
saveImageToPhotsAlbum,实际实现时可统一为saveImageToPhotosAlbum,避免日志歧义。
