名词解释:

space: 即为namespace。是用户的域名前缀，可以在多媒体云控制台查看。

1、准备工作

1) 开通服务，创建空间用于文件存储，参考 接入指引

2) 通过 控制台 进入 SDK 下载，点击生成最新的SDK。

3) 在点击跳转到的页面中， 选择语言、appkey和iOS的bundle id。 这些信息会和SDK中的安全图片关联。安全图片包含了应用本身的特征指纹和顽兔多媒体服务的授权密钥，是应用访问顽兔多媒体服务的唯一身份认证，需要包含在应用的安装包中。

4) 下载生成SDK，SDK里面会包含yw_1222.jpg安全图片文件，安全图片包含“专属”信息，开发者需妥善保存。

2、运行 Demo

下载ios demo 点击下载。

注意：demo需要6.3.2以上版本的xcode才能运行！

1) 解压缩后打开 iOS SDK文件夹 ，media.sdk文件夹下为所有顽兔多媒体云的依赖包。示例如下

2) 修改bundle id。打开xcode工程设置页面的General标签页，修改页面上的Bundle Identifier。

3) 将上一步下载的安全图片 yw_1222.jpg 替换掉OneSDK目录的同名文件。

4) 双击打开media.sdk.ios.demo.isv.xcodeproj文件。打开media.sdk.ios.demo.isv目录下的ALBBMedia.h文件，修改DEMO_NAMESPACE属性为你自己创建的namespace名称。

5) 点击左上角的运行按钮会启动虚拟机。（请使用最新的 xcode 版本打开项目文件，低版本 xcode 不保证兼容性）

6) 点击选择图片，在图库中选择一张图片上传。点击使用图库，或者数据，或者文件方式上传。

7) 通过控制台的空间管理功能，浏览 Demo 上传的图片。

3、工程配置

3.1 SDK包说明

顽兔多媒体云依赖包(必选)

1. 请引入所有在控制台下载到的framework包。
2. 请copy所有在控制台下载到的bundle包

3.2 xcode工程设置

1) 将下载到的身份图片yw_1222.jpg 复制到xcode工程下，并copy到BundleResources里，注意不能改名。如果直接使用SDK demo，请替换demo根目录的同名文件。如图:

2) copy下载的SDK包目录下baichuan.bundle文件 到BundleResources里。

3) 修改Other Linker Flags， 添加-ObjC。

4) 引入依赖的系统库。

• CoreFoundation.framework
• libz.dylib
• ImageIO.framework
• CoreGraphics.framework
• CFNetwork.framework
• MobileCoreServices.framework
• AssetsLibrary.framework
• CoreData.framework
• Security.framework
• SystemConfiguration.framework
• CoreTelephony.framework
• CoreLocation.framework
• UIKit.framework
• Foundation.framework

5) 修改 App Transport Security policy 在项目的plist文件增加以下配置。

6) 关闭 Enable Bitcode 在Build Settings页面，修改Enable Bitcode为NO。

4、SDK 接口说明

4.1 SDK初始化

示例代码

[[ALBBSDK sharedInstance] asyncInit];

获取ALBBMediaService实例

id<ALBBMediaServiceProtocol> mediaService = [[ALBBSDK sharedInstance] getService:@protocol(ALBBMediaServiceProtocol)];

4.2 上传接口

4.2.1 简单异步上传接口

接口描述

/**
*  @brief简单上传接口
*
*  @param data         文件data
*  @param ns           space
*  @param fileName     服务器上存储的文件名
*  @param dir          服务器上存储的路径
*  @param progress     上传进度
*  @param success      上传成功通知
*  @param upload       上传失败通知
*
*  @return 任务唯一标识
*/
- (NSString *)uploadByData:(NSData *)data
                     space:(NSString *)ns
                  fileName:(NSString *)fileName
                       dir:(NSString *)dir
                  progress:(TFEUploadProgress)progress
                   success:(TFEUploadSuccess)success
                    failed:(TFEUploadFailed)failed;

参数列表：

参数	类型	说明
data	NSData	上传文件的数据
ns	NSString	空间名
fileName	NSString	文件名
dir	NSString	文件夹名
progress	TFEUploadProgress	上传进度
success	TFEUploadSuccess	上传成功通知
上传成功通知	TFEUploadFailed	上传相关错误

示例代码

[mediaService uploadByData:data
                     space:@"testNamespace"
                  fileName:"sample.jpg"
                       dir:"/test"
                  progress:nil
                   success:nil
                    failed:nil];

4.2.2 异步上传接口

接口描述

/**
* 上传接口
* 
* @param parameters 上传参数
* @param options 上传选项
* @param notification 上传回调
* @param error 上传产生的错误
* @return uniqueId 上传任务id
*/
- (NSString *)upload:(TFEUploadParameters *)parameters options:(TFEUploadOptions *)options notification:(TFEUploadNotification *)notification;

参数列表：

参数	类型	说明
parameters	TFEUploadParameters	上传相关参数配置
options	TFEUploadOptions	上传相关选项
notification	TFEUploadNotification	上传相关回调
error	NSError	上传相关错误

示例代码

TFEUploadParameters *params = [TFEUploadParameters paramsWithData:data space:@"testNamespace" fileName:@"sample.jpg" dir:@"/test"];
[mediaService upload:params notification:nil];

4.2.3 支持的上传方式

可以修改TFEUploadParameters，通过不同的构造函数，可以使用不同的上传方式。

1) 使用图库url上传

TFEUploadParameters *parms = [TFEUploadParameters
        paramsWithAssertUrl:assetUrl
                      space:myNamespace
                   fileName:[self uniqueString] dir:@"test"];

注意

由于ios图库api不支持对“我的照片流”图库URL的读取。所以上传“我的照片流”里面的文件，请使用NSData的方式上传(使用TFEUploadParameters的paramsWithData方法获取实例)

2) 使用NSData上传

TFEUploadParameters *parms = [TFEUploadParameters
             paramsWithData:data
                      space:myNamespace
                   fileName:[self uniqueString] dir:@"test"];

3) 使用文件路径上传

TFEUploadParameters *parms = [TFEUploadParameters
         paramsWithFilePath:filePath
                      space:myNamespace
                   fileName:[self uniqueString] dir:@"test"];

4.3 加载接口

4.3.1 同步加载

接口描述

/**
*  同步加载
*
*  @param url 图片url
*  @param options 选项
*  @param error 发生的错误
*
*  @return TFELoadSession
*/
- (TFELoadSession *)load:(NSString *)url options:(TFELoadOptions *)options error:(NSError **)error;

参数列表：

参数	类型	说明
url	NSString	图片url
options	TFELoadOptions	选项
error	NSError	错误

示例代码

[mediaService load:@"http://testNamespace.image.alimmdn.com/test/sample.jpg" options:nil error:nil];

4.3.2 异步加载

接口描述

/**
*  异步加载
*
*  @param url      url
*  @param notifications 异步加载完的回调
*  @param options 选项
*  @param error    发生的错误
*
*  @return NSString uniqueId 任务的唯一标示
*/
- (NSString *)asynLoad:(NSString *)url notifications:(TFELoadNotifications *)notifications options:(TFELoadOptions *)options;

参数列表：

参数	类型	说明
url	NSString	图片url
notifications	TFELoadNotifications	加载回调
options	TFELoadOptions	加载选项
error	NSError	error

示例代码

[mediaService asynLoad:@"http://testNamespace.image.alimmdn.com/test/sample.jpg" notifications:nil options:nil];

4.4 设置全局的通知监听

接口描述

/**
 *  公共的通知，所有文件的上传通知都会调用公共的通知
 *
 *  @param notification TaeFileNotification
 */
- (void)setGlobalNotification :(TFEUploadNotification *)notification;

示例代码

[mediaService setGlobalNotification:[TFEUploadNotification
              notificationWithProgress:^(TFEUploadSession *session, NSUInteger progress) {
                  NSLog(@"%@ - %lu", session.uniqueIdentifier, (unsigned long) progress);
              }
                               success:^(TFEUploadSession *session, NSString *url) {
                                   NSLog(@"%@", session.uniqueIdentifier);
                               }
                                failed:^(TFEUploadSession *session, NSError *error) {
                                   NSLog("%@", error)

                                }
      ]];

4.5 取消所有任务

接口描述

/**
 *  取消所有上传任务
 */
- (void) cancelAllUploads;

示例代码

[mediaService cancelAllUploads];

4.6 取消某个任务

接口描述

/**
 *  取消特定任务
 *  @param uniqueIdentifier    本地上传id，用于标识本地一个任务
 *
 */
- (void) cancelUploadByUniqueId:(NSString *)uniqueIdentifier;

示例代码

[mediaService cancelUploadByUniqueId:@"<identifier>"];

4.7 图片处理

接口描述

/**
*  获取通过变形转换之后的url
*
*  @param oprtions 图片处理选项
*
*  @return 变形转换之后的url
*/
- (NSString *)getTransferedURL:(TFEImageTransferOptions *)options error:(NSError **)error;

参数列表：

参数	类型	说明
options	TFEImageTransferOptions	图片处理相关参数
error	NSError	转换遇到的错误

示例代码

TFEImageTransferOptions *options = [[TFEImageTransferOptions alloc] initWithNamespace:@"testNamespace" dir:@"/test" name:@"sample.jpg"];
options.width =300;
options.height =300;
options.limit = YES;
options.multiple =2;
options.shortEdge = YES;
options.rotate = 20;
options.quality =80;
[mediaService getTransferedURL:options error:nil];

5、文件上传大小限制

图片文件最大不能超过20m，其他类型文件没有限制

6、状态和错误处理

6.1 状态

//ready，任务刚添加的状态
TFETaskStatusReady = 0,
//任务失败
TFETaskStatusFailed,
//任务被取消
TFETaskStatusCanceled,
//任务正在运行中
TFETaskStatusRunning,
//任务被暂停
TFETaskStatusSuspend,
//任务成功
TFETaskStatusSuccess

6.2 错误处理

错误	错误码	说明	处理
TFEErrorUnKnown	0	未知错误	重试上传
TFEErrorFileNotExist	1001	文件不存在	检查文件是否存在
TFEErrorFileTypeDisallow	1002	文件类型不允许	无
TFEErrorFileRetryTimesExceed	1003	文件重试次数超出	可能是由于网络原因引起的重试上传失败。等网络好了之后重试上传
TFEErrorMultipartRetryTimesExceed	1004	文件分片重试次数超出, 当文件>4m的时候，sdk会自动做分片上传，分片有3次的重试次数。如果超出，会出现这个错误。	重试上传
TFEErrorUploadError	1005	上传请求已发出，服务端返回了错误	请打印出error的具体内容，以及session的requestId字段。到状态码页面查找解决方案
TFEErrorLoadError	1006	下载错误	请打印出error的具体内容，根据情况解决
TFEErrorFileReadException	1007	文件读取错误	无
TFEErrorAssetsReadException	1008	本地图库读取错误	无
TFEErrorNetworkNotReachable	1009	网络连接错误	无
TFEErrorNetworkChanged	1010	网络切换	无
TFEErrorConnectionTimeout	1011	网络连接超时	无
TFEErrorImageSizeExceed	1012	图片大小超出上传限制	设置正确的sizelimit值，或者看看是否超出了文件上传大小限制
TFEErrorIllegalArgument	1013	参数错误	无
TFEErrorLoadRequestError	1014	加载请求错误	无
TFEErrorSessionError	1015	session错误	重试上传
TFEErrorAuthFailed	1016	鉴权错误	鉴权错误，检查namespace是否设置正确
TFEErrorCanceled	2001	cancle操作返回的错误	重试上传

7、附录

参数：TFEUploadNotification

参数	类型	说明
TFEUploadProgress	block	上传进度通知
TFEUploadSuccess	block	上传成功通知
TFEUploadFailed	block	上传失败通知（包括取消)

参数TFEUploadParameters：

参数	类型	说明
assertUrl	NSURL	系统图库url
fileName	NSString	支持自定义变量和魔法变量
dir	NSString	支持自定义变量和魔法变量
data	NSData	文件数据
filePath	NSString	文件本地路径
space	NSString	policy字段，用户空间名
sizeLimit	int	policy字段，文件大小限制，只能设置一个大于8，小于10 * 1024 * 1024的数值
customMetas	NSDictionary	用户自定义的头部信息，在下载图片的时候可以由http header获取
customParms	NSDictionary	用户自定义的变量，可以替换remoteCall body或者文件名或者文件夹名中的placeholder
remoteCall	TFEUploadRemoteCall	policy字段，远程调用相关参数，可以在上传时候回调服务器
customPolicys	NSDictionary	用户自定义的policy, policy文档有的，而TFEUploadParameters类不支持的参数，可以通过自定义policy设置

参数TFEUploadRemoteCall：

参数	类型	说明
urls	NSArray	远程调用的url，可以设置多个。使用全的url，例：http://www.taobao.com;http://110.79.128.79/preload.php
host	NSString	当url中都是ip的时候，可以设置host
body	NSString	调用远程url时的body
bodyType	NSString	调用远程url时的http contentType

参数TFEUploadOptions：

参数	类型	说明
connectionTimeout	int	单位秒，多少秒之内服务器没有响应则上传失败，默认为30妙
userInfo	id	用户自定义的数据，如果设置了，会在TFESession中获取到

参数TFEImageTransferOptions：

参数	类型	说明
url	NSString	图片的原始url
shortEdge	BOOL	是否短边优先
width	int	长度，1-4096
height	int	高度，1-4096
absoluteQuality	BOOL	是否使用绝对质量
quality	int	质量，1-100
rotate	int	0-360
multiple	int	倍数, 倍数和长宽乘积不能超过4096
immobilize	BOOL	是否固定宽高, 默认否
cut	BOOL	是否裁剪
orient	BOOL	有些相机拍的照片会出现旋转，本参数就是根据原图 EXIF 信息自动适应方向
advanceCut	TFEImageAdvanceCut	高级裁剪选项
brightness	int	亮度 -100 - 100
contrast	int	对比度 -100 - 100
limit	BOOL	如果生成的图片大于原图将返回原图
format	TFEImageFormat	生成的图片格式
watermark	TFEImageWatermark	水印

参数TFELoadOptions：

参数	类型	说明
cachePolicy	NSURLRequestCachePolicy	使用的缓冲策略
connectionTimeout	int	服务器无响应的最大时间
httpMethod	NSString	加载使用的httpMethod
requestHeaders	NSDictionary	加载使用的http header
requestData	NSData	加载使用的http body data
userInfo	id	用户自定义数据，会在session里面返回给用户

返回TFELoadSession：

参数	类型	说明
url	NSString	load的url
userInfo	id	用户传入的自定义数据
responseData	NSData	返回的data
response	NSHTTPURLResponse	response
customMetas	NSDictionary	用户的自定义meta数据
contentType	NSString	http header Content-Type
httpStatus	int	http 状态码
status	TFETaskStatus	任务状态

参数TFELoadNotification：

参数	类型	说明
success	TFELoadSuccess	加载完成回调
progress	TFELoadProgress	加载进度回调
failed	TFELoadFailed	加载失败回调

FAQ

关于此文档暂时还没有FAQ