HiFiVeSDK接入文档

2019-08-28 本文已影响0人 CGRect

二、SDK集成

2.1 系统支持

iOS8.0以上

2.2运行环境

建议使用XCode8.0以上版本进行编译。

2.3集成SDK

目前仅提供静态库接入方案。

Cocoapods集成
手动集成

2.3.1 Cocoapods集成

添加如下语句加入你的Podfile文件中。

pod 'HFVMusic'

执行pod install或者pod update后集成SDK到项目工程。
运行项目名.xcworkspace文件打开工程。

2.3.2 手动集成

在此下载HFVMusic,放入你的工程目录。
打开工程，依次选择TARGET -> General -> Link Frameworks With Libraries，添加 HFVMusic.framework，Status 设置为 Requied。

Target设置
此外，HFVMusic还依赖了一些三方库,开发者同样需要集成进项目中。

三方库	版本	描述
AFNetworking	3.2.1	网络通信
SAMKeychain	1.5.3	钥匙串管理
MJExtension	3.0.17	模型转换

三、SDK使用

3.1 日志输出

可通过设置是否为debug，来控制SDK相关信息打印

#ifdef DEBUG
    [HFVMusic setRunOnDebug:YES];
#else
    [HFVMusic setRunOnDebug:YES];
#endif

3.2 SDK初始化

建议在AppDelegate中导入#import <HFVMusic/HFVMusic.h>,调用如下API进行SDK初始化操作

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    [HFVMusic startAppId:@"APPID" InSecret:@"SECRET"];
    
    return YES;
}

3.3 用户初始化

当获取到用户信息或者房间信息之后，调用如下API，HFV平台将会为该用户创建空间

[HFVMusic setUserId:@"UserId" name:@"NAME" anchor:YES result:^(HFVAuthorizationModel * _Nonnull authorization) {
        
} error:^(NSError * _Nonnull error) {
        
}];

四、API列表

4.1 初始化SDK

需要在调用其他API之前初始化SDK，建议在AppDelegate中调用。

+ (void)startAppId:(NSString *)appId
          InSecret:(NSString *)secret;

请求参数

参数	必填	描述
appId	是	开放平台申请appId
secret	是	开放平台申请secret

4.2 设置debug模式

开发者调用API时会打印相应信息辅助开发者开发，开发者可以选择是否关闭信息，建议在release模式关闭，以提高性能。

+ (void)setRunOnDebug:(BOOL)debug;

请求参数

参数	必填	描述
debug	是	YES：会进行日志输出，NO：不会进行日志输出

4.3 初始化用户

HFV平台将会为该用户创建空间。因SDK需要唯一标识作为userId，因此建议开发者使用自己用户的userId。

+ (NSInteger)creatUser:(NSString *)userId
                  name:(NSString *)name
                anchor:(BOOL)isAnchor
                result:(void (^)(HFVSDKInfo *authorization))result
                 error:(void (^)(NSError *error))errorCall;

请求参数

参数	必填	描述
userId	是	用户ID
name	是	用户名
isAnchor	是	是否是主播; YES-是, NO-否

业务错误码

错误码	错误描述	解决方案
-	-	-

4.4 检索主播歌单

musicId为歌曲加入歌单的序号，自增属性，新加入的比之前加入的更大。

查询在指定歌曲之后加入的集合

+ (NSInteger)musicBiggerThan:(nullable NSString *)musicId
                        size:(nullable NSString *)size
                      userId:(NSString *)userId
                      roomId:(nullable NSString *)roomId
                 mediaAction:(NSString *)mediaAction
                      result:(void (^)(NSArray <HFVMusicInfo *>*musics))result
                       error:(void (^)(NSError *error))errorCall;

请求参数

参数	必填	描述
musicId	是	指定歌曲的id
size	是	查询集合数量
userId	是	主播ID
roomId	否	房间ID
mediaAction	是	操作类型:K-k歌; P-听歌

业务错误码

错误码	错误描述	解决方案
-	-	-

查询在指定歌曲之前加入的集合

+ (NSInteger)musicSmallerThan:(nullable NSString *)musicId
                         size:(nullable NSString *)size
                       userId:(NSString *)userId
                       roomId:(nullable NSString *)roomId
                  mediaAction:(NSString *)mediaAction
                       result:(void (^)(NSArray <HFVMusicInfo *>*musics))result
                        error:(void (^)(NSError *error))errorCall;

请求参数

参数	必填	描述
musicId	是	指定歌曲的id
size	是	查询集合数量
userId	是	主播ID
roomId	否	房间ID
mediaAction	是	操作类型:K-k歌; P-听歌

业务错误码

错误码	错误描述	解决方案
-	-	-

4.5 检索主播歌单中歌曲数量

获取主播K歌列表和播放列表的统计信息

+ (NSInteger)musicCount:(NSString *)userId
                 result:(void (^)(HFVMusicCount *count))result
                  error:(void (^)(NSError *error))errorCall;

请求参数

参数	必填	描述
userId	是	主播ID

业务错误码

错误码	错误描述	解决方案
-	-	-

4.6 将该歌曲添加入歌单

将指定歌曲加入主播的K歌列表和播放列表

+ (NSInteger)addToPlayList:(NSString *)userId
                    roomId:(nullable NSString *)roomId
                   musicNo:(NSString *)musicNo
               mediaAction:(NSString *)mediaAction
                    result:(void (^)(void))result
                     error:(void (^)(NSError *error))errorCall;

请求参数

参数	必填	描述
userId	是	主播ID
roomId	否	房间ID
musicNo	是	歌曲ID
mediaAction	是	操作类型:K-k歌; P-听歌

业务错误码

错误码	错误描述	解决方案
10610	歌曲已在歌单	重新选择新歌曲
10611	请使用主播账号	检测应用初始化，是否主播anchor参数未生效

4.7 将该歌曲移出歌单

将指定歌曲移出主播的K歌列表和播放列表

+ (NSInteger)deleteFromPlayList:(NSString *)userId
                         roomId:(nullable NSString *)roomId
                        musicNo:(nullable NSString *)musicNo
                    mediaAction:(NSString *)mediaAction
                         result:(void (^)(void))result
                          error:(void (^)(NSError *error))errorCall;

请求参数

参数	必填	描述
userId	是	主播ID
roomId	否	房间ID
musicNo	是	歌曲ID
mediaAction	否	操作类型:K-k歌; P-听歌

业务错误码

错误码	错误描述	解决方案
-	-	-

4.8 检索歌曲标签

获取资源库所有歌曲的标签分类。

+ (NSInteger)musicTags:(nullable NSString *)current
                  size:(nullable NSString *)size
                result:(void (^)(NSArray<HFVMusicTag *> *musics))result
                 error:(void (^)(NSError *error))errorCall;

请求参数

参数	必填	描述
current	否	当前页默认1
size	否	页大小默认10，最大1000

业务错误码

错误码	错误描述	解决方案
-	-	-

4.9 根据标签检索歌曲集合

通过检索歌曲标签API获取的标签来检索该标签下方的所有歌曲。

+ (NSInteger)searchMusicByTag:(nullable NSString *)current
                         size:(nullable NSString *)size
                          tag:(NSString *)tag keyword:(nullable NSString *)keyword
                       result:(void (^)(NSArray <HFVMusicInfo *>*musics))result
                        error:(void (^)(NSError *error))errorCall;

请求参数

参数	必填	描述
current	否	当前页默认1
size	否	页大小默认10，最大1000
tag	是	标签
keyword	否	关键词

业务错误码

错误码	错误描述	解决方案
-	-	-

4.10 检索歌曲资源

获取歌曲的原声、伴奏歌词url地址

+ (NSInteger)resource:(NSString *)userId
             userName:(NSString *)userName
               roomId:(nullable NSString *)roomId
              musicNo:(NSString *)musicNo
          mediaAction:(NSString *)mediaAction
               result:(void (^)(HFVMusicResource *resource))result
                error:(void (^)(NSError *error))errorCall;

请求参数

参数	必填	描述
userId	是	主播ID
userName	是	主播名字
roomId	否	房间ID
musicNo	是	歌曲ID
mediaAction	是	操作类型:K-k歌; P-听歌

业务错误码

错误码	错误描述	解决方案
10611	请使用主播账号	检测应用初始化，是否主播anchor参数未生效

4.11 下载LRC资源

下载歌词lrc文件，文件编码格式UTF-8。

+ (NSInteger)downLoadLRC:(NSURL *)remoteUrl
                      to:(NSURL *)localUrl
                  result:(void (^)(NSURL *filePath))result
                   error:(void (^)(NSError *error))errorCall;

请求参数

参数	必填	描述
remoteUrl	是	端URL
localUrl	是	本地存放路径

业务错误码

错误码	错误描述	解决方案
-	-	-

4.12 推荐歌曲

推荐歌曲

+ (NSInteger)recommendMusic:(nullable NSString *)current
                       size:(nullable NSString *)size
                     result:(void (^)(NSArray <HFVMusicInfo *>*musics))result
                      error:(void (^)(NSError *error))errorCall;

请求参数

参数	必填	描述
current	否	当前页默认1
size	否	页大小默认10，最大1000

业务错误码

错误码	错误描述	解决方案
-	-	-

4.13 取消任务

大部分API均有网络参与，某些场景开发者可能需要取消某一个API调用，可通过API返回的请求唯一标识来取消该API的调用

/**
 取消某个任务

 @param identifier 请求唯一标识
 */
+ (void)cancleTaskWithIdentifier:(NSUInteger)identifier;

请求参数

参数	必填	描述
identifier	是	请求唯一标识

业务错误码

错误码	错误描述	解决方案
-	-	-

五、API状态码

所有API的公共错误码

错误码	错误描述	解决方案
10500	internal fail	重试
10504	parameter validation error	检测参数传值
10400	service error
10401	未登录（签名错误）	检测sign签名生成算法，是否正确
10602	应用账户不存在	检测输入appId和secret
10502	登录已超时，请重新登录	重新登录
10201	no data
10600	无效应用	请检测输入包名或应用配置参数
10201	非法包名	请检测输入包名

成功响应码

响应码	描述
10200	success

六、响应数据model

用户认证结果model

@interface HFVSDKInfo : HFVBaseModel

    
/**
 应用创建时间
 */
@property (nonatomic, copy) NSString * createTime;
    
/**
  logo 图标
 */
@property (nonatomic, copy) NSString * icon;
    
/**
 授权名称
 */
@property (nonatomic, copy) NSString * name;
    
/**
 应用版本
 */
@property (nonatomic, copy) NSString * releaseVersion;
    
/**
  系统版本
 */
@property (nonatomic, assign) NSInteger version;

@end

音乐基础信息model

@interface HFVMusicInfo : HFVBaseModel
    

/**
 专辑名
 */
@property (nonatomic, copy) NSString * albumName;
@property (nonatomic, assign) NSInteger bpm;
    
/**
 封面图
 */
@property (nonatomic, copy) NSString * coverUrl;
@property (nonatomic, copy) NSString * createTime;
    
/**
 时长
 */
@property (nonatomic, assign) NSInteger duration;
    
/**
 媒体操作类型：K-k歌; P-听歌
 */
@property (nonatomic, copy) NSString * mediaAction;
    
/**
 歌曲名
 */
@property (nonatomic, copy) NSString * musicName;
    
/**
 歌曲编号
 */
@property (nonatomic, copy) NSString * musicNo;
    
/**
 歌手
 */
@property (nonatomic, copy) NSString * musicSinger;
    
/**
 时间
 */
@property (nonatomic, copy) NSString * dayTime;
@property (nonatomic, assign) double price;
@property (nonatomic, assign) double size;

- (BOOL)isEqualToMusic:(HFVBaseMusicModel *)music;

@end

音乐资源model

@interface HFVMusicResource : HFVBaseModel

/**
 伴奏地址
 */
@property (nonatomic, copy) NSString * accompanyUrl;
    
/**
 歌词地址
 */
@property (nonatomic, copy) NSString * lyricUrl;
    
/**
 原唱地址
 */
@property (nonatomic, copy) NSString * majorUrl;
    
/**
 交易号
 */
@property (nonatomic, copy) NSString * outTradeNo;

@end

主播歌单统计model

@interface HFVMusicCount : HFVBaseModel

/**
 k歌数
 */
@property (nonatomic, assign) NSInteger knum;
    
/**
 听歌数
 */
@property (nonatomic, assign) NSInteger pnum;
    
/**
 总曲数
 */
@property (nonatomic, assign) NSInteger total;

@end

歌曲标签model

@interface HFVMusicTag : HFVBaseModel
    
/**
 标签名
 */
@property (nonatomic, copy) NSString * name;

@end