iOS 分发推荐SDK 接入指南(v1.0.15)
Deploy target : iOS 8.0.
1 如何接入
1.1 在项目的 Podfile 中，添加如下依赖：
target 'YourProject' do
pod 'SHWRecommendSDK', '~> 1.0.15'
end1.2 更新安装
pod update
pod install
2 Regist your app.
Get your AppKey in our web site. appKey值可从新华智云接口人获取（网站建设中，目前请联系接口人）
3 How to use
3.1 设置AppKey和AppSecret
int main(int argc, char *argv[]) {
@autoreleasepool {
//...
//注意: 如果需要精准推荐，用户登录行为需要在此时记录。
[SHWRDContextService setUserId:@"user id"];
[SHWRDContextService startWithAppKey:@"app key" appSecret:@"app secret"];
[SHWRUConfig startWithAppKey:SHWFF_APP_KEY appSecret:SHWFF_APP_SECRET];
//...
}
}分发推荐SDK内部使用巴吉度，并使用一套app key配置了巴吉度，所以如果使用分发推荐SDK，就不用配置巴吉度了。
3.2 推荐新闻id服务的接口
//SHWRDNewsIdService.h
/**
* 获取新闻Id的接口。
*/
@interface SHWRDNewsIdService : NSObject
/**
* @brief 获取推荐新闻id列表。
*
* @param completeHandler 包含了新闻id列表，具体结构见文档3.2.1。
*/
+ (void)recommendNewsIdListWithCompleteHandler:(SHWRecommendResponseComplete)completeHandler;
/**
* @brief 基于baseId，向上或向下，获取推荐新闻id列表
*
* @param baseId 基于这条新闻Id，向direction来获取更多推荐新闻Id
* @param from baseId的来源。来自数闻、还是媒体方。
* @param direction 基于baseId的方向
* @param completeHandler 包含了新闻id列表，具体结构见文档3.2.1。
*/
+ (void)recommendNewsIdListWithBaseId:(NSString *)baseId from:(SHWRD_NEWSID_SOURCE)from direction:(SHWRD_RECOMMEND_DIRECTION)direction completeHandler:(SHWRecommendResponseComplete)completeHandler;
/**
* @brief 基于baseId和lastId，获取之间（不含baseId，lastId）的推荐新闻id列表
*
* @param baseId 基于这条新闻Id以后
* @param baseIdFrom baseId的来源。来自数闻、还是媒体方。
* @param lastId 基于这个新闻Id之前
* @param lastIdFrom lastIdFrom的来源。来自数闻、还是媒体方。
* @param completeHandler 包含了新闻id列表，具体结构见文档3.2.1。
*/
+ (void)recommendNewsIdListWithBaseId:(NSString *)baseId baseIdFrom:(SHWRD_NEWSID_SOURCE)baseIdFrom lastId:(NSString *)lastId lastIdFrom:(SHWRD_NEWSID_SOURCE)lastIdFrom completeHandler:(SHWRecommendResponseComplete)completeHandler;
/**
* @brief 基于newsId，获取其相关新闻id列表
*
* @param newsId 新闻id，据此id进行相关新闻推荐。
* @param from newsId的来源。来自数闻、还是媒体方。
* @param completeHandler 包含了新闻id列表，具体结构见文档3.2.1。
*/
+ (void)relatedNewsIdListForNews:(NSString *)newsId from:(SHWRD_NEWSID_SOURCE)from completeHandler:(SHWRecommendResponseComplete)completeHandler;
//typedef void (^SHWRecommendResponseComplete)(NSDictionary *_Nullable result, NSError *_Nullable error);####3.2.1 本接口中SHWRecommendResponseComplete的json结构示例
//typedef void (^SHWRecommendResponseComplete)(NSDictionary *_Nullable result, NSError *_Nullable error);
//result的json结构如下
{
"success": true,
"code": "",
"msg": "",
"requestId": "1251dc9f8b104eaf9528b06f6f8f0194",
"data": {
"total": 5,
"tag": "da38eeb5-a9ab-4bd3-8738-c3685be70c3d",
"hasMore": true,
"list": [{
"id": "140753524548972561",
"from": 2
}, {
"id": "140753525720231944",
"from": 2
}, {
"id": "140753524542681096",
"from": 2
}, {
"id": "140753525694017553",
"from": 2
}, {
"id": "140745993570234374",
"from": 1
}]
}
}
###3.3 获取数闻 新闻信息列表的接口
//SHWRDNewsBriefService.h
/**
* @brief 根据新闻id列表，获取新闻简要信息。用于列表页展示。
*
* @param newsIdList 新闻id列表。必须是智云分发系统的ID
* @param completeHandler 包含了新闻信息列表，具体结构见文档3.3.1。
*/
+ (void)newsBriefListFromShuWen:(NSArray<NSString *> *)newsIdList completeHandler:(SHWRecommendResponseComplete)completeHandler;
/**
* @brief 根据关键词，获取新闻id列表的搜索结果。
*
* @param queryString 关键词
* @param lastId 上次返回中最后一个Id，可以为nil
* @param count 数量
* @param order 输出结果的排序方法，时间、相关度
* @param completeHandler 包含了新闻信息列表，具体结构见文档3.3.1。
*/
+ (void)search:(NSString *)queryString lastId:(NSString *)lastId count:(NSUInteger)count order:(SHWRD_SEARCH_RESULT_ORDER)order completeHandler:(SHWSearchResponseComplete)completeHandler;
//typedef void (^SHWSearchResponseComplete)(NSDictionary *_Nullable result, NSError *_Nullable error);
####3.3.1 SHWRecommendResponseComplete中包含的json结构示例，主要内容是新闻brief信息
//如果新闻是智云新闻库中的新闻id，从id获取news brief的json返回如下
{
"success": true,
"code": "",
"msg": "",
"requestId": "d4bed6ea8eb44f3fb2054d9d95e6186a",
"data": {
"count": 2,
"first_id": "132243272506561544",
"last_id": "132242643557030922",
"news": [
{
"news_id": "132243272506561544",
"title": "都昌县烟草专卖局查获一起涉烟大要案件",
"source": "中国江西网",
"gmt_publish": 1519635236000,
"hot_index": 1,
"selection": false,
"category": [
"社会"
],
"thumbnail_img": [],
"url": "https://i.xinwen.cn/132243272506561544.html",
"summary_create_time": null,
"summary_update_time": null,
"summary": null,
"content": "内容"
},
{
"news_id": "132242643557030922",
"title": "创新企业用工需求明显增多! 滕州举办春风行动招聘会供岗两万多",
"source": "齐鲁网",
"gmt_publish": 1519635180000,
"hot_index": 1,
"selection": false,
"category": [
"社会"
],
"thumbnail_img": [
"https://m.newscdn.cn/41cdcf45-9ba7-4062-8a4e-d3594784ba7f.jpg!thumbnail"
],
"url": "https://i.xinwen.cn/132242643557030922.html",
"summary_create_time": null,
"summary_update_time": null,
"summary": null,
"content": "内容"
}]
}
}
###3.4 媒体和数闻新闻混搭的列表接口
//SHWRDCustomedNewsBriefService.h
@protocol SHWRDCustomedNewsBriefDelegate
/**
* @brief 根据媒体新闻id列表，获取媒体新闻信息列表。
* ！！！newsBriefList中新闻需要保持newsIdList中的顺序。
* @param newsIdList 媒体新闻id列表。
* @param callback 参数newsBriefList: 媒体新闻信息的json数组。
*/
- (void)arrayOfNewsLiteFromMeiti:(NSArray<NSString *> *)newsIdList callback:(void (^)(NSArray *newsBriefList))callback;
/**
* @brief 处理数据转换
* 根据数闻新闻json，媒体新闻json， 获取媒体自定义数据结构
*
* @param item 数闻新闻json，媒体新闻json
*
* @return 媒体自定义的新闻信息类。
*/
- (_Nonnull id)objectFromArrayItem:(_Nonnull id)item from:(SHWRD_NEWSID_SOURCE)source;
@end
/**
* 获取媒体和数闻新闻信息混搭的列表服务，要求App实现SHWRDCustomedNewsBriefDelegate的两个方法
* 是对SHWRDNewsIdService和SHWRDNewsBriefService的封装
*/
@interface SHWRDCustomedNewsBriefService : NSObject
@property (nonatomic, weak)id<SHWRDCustomedNewsBriefDelegate> delegate;
/**
* @brief 获取推荐新闻brief信息的列表。
*
* @param completeHandler 包含服务器返回结果的block，newsLiteArray: 媒体自定义新闻对象数组。
* newsLiteFromArray: 新闻信息的from数组
* hasMore：是否有更多新闻，只在没有error的情况下有效。
* error：包含错误信息和错误码
*/
- (void)recommendNewsListWithCompleteHandler:(SHWNewsBriefComplete)completeHandler;
/**
* @brief 基于baseId，向上或向下，获取推荐新闻id列表
*
* @param baseId 基于这条新闻Id，向direction来获取更多推荐新闻Id
* @param from baseId的来源。来自数闻、还是媒体方。
* @param direction 基于baseId的方向
* @param completeHandler 包含服务器返回结果的block，同上
*/
- (void)recommendNewsListWithBaseId:(NSString *)baseId from:(SHWRD_NEWSID_SOURCE)from direction:(SHWRD_RECOMMEND_DIRECTION)direction completeHandler:(SHWNewsBriefComplete)completeHandler;
/**
* @brief 基于baseId和lastId，获取之间（不含baseId，lastId）的推荐新闻id列表
*
* @param baseId 基于这条新闻Id以后
* @param baseIdFrom baseId的来源。来自数闻、还是媒体方。
* @param lastId 基于这个新闻Id之前
* @param lastIdFrom lastIdFrom的来源。来自数闻、还是媒体方。
* @param completeHandler 包含服务器返回结果的block，同上
*/
- (void)recommendNewsListWithBaseId:(NSString *)baseId baseIdFrom:(SHWRD_NEWSID_SOURCE)baseIdFrom lastId:(NSString *)lastId lastIdFrom:(SHWRD_NEWSID_SOURCE)lastIdFrom completeHandler:(SHWNewsBriefComplete)completeHandler;
/**
* @brief 基于newsId，获取其相关新闻id列表
*
* @param newsId 新闻id，据此id进行相关新闻推荐。
* @param from newsId的来源。来自数闻、还是媒体方。
* @param completeHandler 包含服务器返回结果的block，同上
*/
- (void)relatedNewsListForNews:(NSString *)newsId from:(SHWRD_NEWSID_SOURCE)from completeHandler:(SHWNewsBriefComplete)completeHandler;
3.5 通用配置接口
//SHWRDContextService.h
/**
* @brief 设置用户账号
用于根据用户账号进行精准推荐，需要app在账户生命周期变化时调用。（如：启动时、每次登录、退出登录、cookie过期）
*
* @param userId 用户账号id，nil表示未登录、或退出登录后的游客状态
*/
+ (void)setUserId:(NSString *)userId;
/**
* @brief 设置每页拉取的最大新闻数，默认20，范围10-50
*
* @param count 最大数量
*/
+ (void)setRecommendNewsCount:(NSUInteger)count;
/**
* 推荐新闻条数，每次请求拉取条数
*/
+ (NSUInteger)recommendNewsCount;
/**
* @brief 设置相关新闻的最大条数，默认5。
*
* @param count 最大数量
*/
+ (void)setRelateNewsCount:(NSUInteger)count;
/**
* 相关新闻条数
*/
+ (NSUInteger)relateNewsCount;
###3.6 用户行为接口
//SHWRDLogService.h
/**
* @brief 用户偏好获取, 用于根据用户偏好进行精准推荐
*
* @param behavior 包括：新闻点击、广告点击、分享、收藏、点赞、不喜欢、页面停留时间等。
* @param targetid 新闻id或广告id。
* @param from newsId的来源。来自数闻、还是媒体方。
* @param duration 连续型事件的持续时间，如：页面停留时间事件。其他时间传0即可。
* @param value 事件辅助参数，目前只有“不喜欢“事件的原因。
* @param args 用户自定义参数。
*/
+ (void)userbehavior:(SHWRD_ONCE_BEHAVIOR)behavior targetid:(NSString *)targetid from:(SHWRD_NEWSID_SOURCE)from duration:(long)duration value:(NSString *)value args:(NSDictionary *)args;
/**
* @brief 用户偏好批量获取, 用于根据用户偏好进行精准推荐
*
* @param behavior 包括：新闻列表页浏览等。
* @param ids 新闻id数组。
* @param args 用户自定义参数
*/
+ (void)userbehavior:(SHWRD_BATCH_BEHAVIOR)behavior newsidList:(NSArray <SHWRDUserBehaviorItem *>*)ids args:(NSDictionary *)args;
4 错误码
| 错误码 | 错误类型 |
|---|---|
| SW-00993 | 鉴权不通过 |
| SW-00994 | 鉴权过期 |
| SW-00995 | 无效的AccessKey，用户身份识别码无效或不存在 |
| SW-00996 | API服务不存在 |
| SW-00997 | 网关参数不全 |
| SW-00998 | 没有数据或服务器无响应 |
| SW-00301 | 数据格式错误 |
| SW-00302 | 业务参数不全 |
| SW-00303 | 参数类型不对 |
| SW-00305 | 系统内部错误 |
| SW-00399 | 未知错误，联系技术支持 |
5 其它
项目使用了http协议，所以需要适配
- 在
Info.plist中添加NSAppTransportSecurity类型Dictionary。 - 在
NSAppTransportSecurity下添加NSAllowsArbitraryLoads类型Boolean,值设为YES。 - 将
Build setting下Build Options中的Enable Bitcode置为NO。
6 注意
0.x.x版本为测试版，不保证功能可以使用。