Latest 1.0.9
Homepage https://github.com/newsdata/shuwen-recommend-sdk
License MIT
Platforms ios 8.0, requires ARC
Dependencies SHWAnalyticsSDK
Frameworks CoreLocation, CoreTelephony, Foundation, JavaScriptCore, UIKit, WebKit, SystemConfiguration, CoreFoundation, Security
Authors

iOS 分发推荐SDK 接入指南(v1.0.9)

Deploy target : iOS 8.0.

1 如何接入

1.1 在项目的 Podfile 中,添加如下依赖:

target 'YourProject' do
pod 'SHWRecommendSDK', '~> 1.0.9'
end

1.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 {
        //...
        //注意: 如果需要精准推荐,用户登录行为需要在此时记录。
        [SHWFFContextService setUserId:@"user id"];
        [SHWFFContextService startWithAppKey:@"app key" appSecret:@"app secret"];
        //...
    }
}

分发推荐SDK内部使用巴吉度,并使用一套app key配置了巴吉度,所以如果使用分发推荐SDK,就不用配置巴吉度了。

3.2 推荐接口(微接口)

//SHWRcmdMicroService.h
//MARK: 分发推荐
/**
* @brief   获取推荐新闻id列表。
*          每次启动,第一次展示推荐新闻时,以及用户上拉刷新时,调用该接口。
*
* @param   completeHandler   包含服务器返回结果的block,result: 新闻id数组。
*/
+ (void)recommendNewsIdListWithCompleteHandler:(SHWRecommendResponseComplete)completeHandler;

/**
* @brief   获取推荐新闻id列表
*          在app已有推荐新闻的情况下,获取基于baseId的上/下获取更多推荐新闻。用于上拉下拉
*
* @param   baseId              基于这条新闻Id,向direction来获取更多推荐新闻Id
* @param   direction           基于baseId的方向
* @param   completeHandler     包含服务器返回结果的block,result: 新闻id数组。
*/
+ (void)recommendNewsIdListWithBaseId:(NSString *)baseId direction:(SHWFF_RECOMMEND_DIRECTION)direction completeHandler:(SHWRecommendResponseComplete)completeHandler;

/**
* @brief   获取推荐新闻id列表
*          在app已有推荐新闻的情况下,获取基于baseId和lastId之间(不含baseId,lastId)的推荐新闻,用于“更多”
*
* @param   baseId              基于这条新闻Id以后
* @param   lastId              基于这个新闻Id之前
* @param   completeHandler     包含服务器返回结果的block,result: 新闻id数组。
*/
+ (void)recommendNewsIdListWithBaseId:(NSString *)baseId lastId:(NSString *)lastId completeHandler:(SHWRecommendResponseComplete)completeHandler;

/**
* @brief   获取与新闻相关的推荐新闻id列表
*
* @param   newsId              新闻id,服务器根据此id,进行相关新闻推荐。
* @param   from                newsId的来源。SHWFF_NEWSID_SRC_SHUWEN表示newsId是智云CMS中的id,SHWFF_NEWSID_SRC_MEITI表示newsId是媒体自己CMS中的id
* @param   completeHandler     包含服务器返回结果的block,result: 新闻id数组。
*/
+ (void)relatedNewsIdListForNews:(NSString *)newsId from:(SHWFF_NEWSID_SOURCE)from completeHandler:(SHWRecommendResponseComplete)completeHandler;

/**
* @brief   根据新闻id列表,获取新闻简要信息。用于列表页展示。
*
* @param   newsIdList          新闻id列表。必须是智云分发系统的ID
* @param   completeHandler     包含服务器返回结果的block,result: 包含新闻brief信息的数组。
*/
+ (void)newsBriefListFromShuWen:(NSArray<NSString *> *)newsIdList completeHandler:(SHWRecommendResponseComplete)completeHandler;
//如果新闻是智云新闻库中的新闻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.3 更方便的组合接口

//SHWRcmdCombinedService.h
@protocol SHWRcmdCombinedServiceDelegate
/**
* @brief   根据媒体的新闻id列表,在callback中返回一个newslite列表,用于列表页展示。
*          每次启动,第一次展示推荐新闻时,以及用户上拉刷新时,调用该接口。
*          **注意**,call中的newsLite元素的顺序,必须与新闻id列表的顺序保持一致。
* @param   newsIdList  新闻id列表,这些id是媒体自己拥有的新闻id。
* @param   callback    包含服务器返回结果,newsLiteList: 新闻Lite数组。fromList: 元素是对应于新闻Lite的来源。
*/
- (void)arrayOfNewsLiteFromMeiti:(NSArray<NSString *> *)newsIdList callback:(void (^)(NSArray *newsLiteList))callback;
//输入为json,输出的内容就是SHWRcmdNewsLiteService接口中newsLiteArray的数组元素
/**
* @brief   用户对数闻的json以及媒体自己服务器返回的新闻lite数据,进行解析。
*
* @param   item        newsLiteArray中的元素,或者数闻返回的NewsLite的Dictionary结构(具体见文档)。
*
* @return  返回结果,会作为SHWNewsLiteComplete中的newsLiteArray的元素。
*/
- (_Nonnull id)objectFromArrayItem:(_Nonnull id)item from:(SHWFF_NEWSID_SOURCE)source;
@end

/**
*  组合服务,对微服务进行了一定的封装,要求App实现SHWRcmdCombinedServiceDelegate的两个方法
*/
@interface SHWRcmdCombinedService : NSObject
@property (nonatomic, weak)id<SHWRcmdCombinedServiceDelegate> delegate;

//MARK: 分发推荐
/**
* @brief   获取推荐新闻Lite列表。
*          每次启动,第一次展示推荐新闻时,以及用户上拉刷新时,调用该接口。
*
* @param   completeHandler   包含服务器返回结果的block,newsLiteArray: 新闻Lite数组。
*                                                   hasMore是否有更多新闻,只在没有error的情况下有效。
*                                                   error通过NSLocalizedDescriptionKey获取失败Msg, 通过NSLocalizedFailureReasonErrorKey获取errorcode。
*/
- (void)recommendNewsListWithCompleteHandler:(SHWNewsLiteComplete)completeHandler;

/**
* @brief   获取推荐新闻Lite列表
*          在app已有推荐新闻的情况下,获取基于baseId的上/下获取更多推荐新闻。用于上拉下拉
*
* @param   baseId              基于这条新闻Id,向direction来获取更多推荐新闻Id
* @param   direction           基于baseId的方向
* @param   completeHandler   包含服务器返回结果的block,newsLiteArray: 新闻Lite数组。
*                                                   hasMore是否有更多新闻,只在没有error的情况下有效。
*                                                   error通过NSLocalizedDescriptionKey获取失败Msg, 通过NSLocalizedFailureReasonErrorKey获取errorcode。
*/
- (void)recommendNewsListWithBaseId:(NSString *)baseId direction:(SHWFF_RECOMMEND_DIRECTION)direction completeHandler:(SHWNewsLiteComplete)completeHandler;

/**
* @brief   获取推荐新闻Lite列表
*          在app已有推荐新闻的情况下,获取基于baseId和lastId之间(不含baseId,lastId)的推荐新闻,用于“更多”
*
* @param   baseId              基于这条新闻Id以后
* @param   lastId              基于这个新闻Id之前
* @param   completeHandler   包含服务器返回结果的block,newsLiteArray: 新闻Lite数组。
*                                                   hasMore是否有更多新闻,只在没有error的情况下有效。
*                                                   error通过NSLocalizedDescriptionKey获取失败Msg, 通过NSLocalizedFailureReasonErrorKey获取errorcode。
*/
- (void)recommendNewsListWithBaseId:(NSString *)baseId lastId:(NSString *)lastId completeHandler:(SHWNewsLiteComplete)completeHandler;

/**
* @brief   获取与新闻相关的推荐新闻Lite列表
*
* @param   newsId              新闻id,服务器根据此id,进行相关新闻推荐。
* @param   from                newsId的来源。SHWFF_NEWSID_SRC_SHUWEN表示newsId是智云CMS中的id,SHWFF_NEWSID_SRC_MEITI表示newsId是媒体自己CMS中的id
* @param   completeHandler   包含服务器返回结果的block,newsLiteArray: 新闻Lite数组。
*                                                   hasMore是否有更多新闻,只在没有error的情况下有效。
*                                                   error通过NSLocalizedDescriptionKey获取失败Msg, 通过NSLocalizedFailureReasonErrorKey获取errorcode。
*/
- (void)relatedNewsListForNews:(NSString *)newsId from:(SHWFF_NEWSID_SOURCE)from completeHandler:(SHWNewsLiteComplete)completeHandler;

3.4 用户行为接口

//SHWFFContextService.h
/**
* @brief   设置用户账号
用于根据用户账号进行精准推荐,需要app在账户生命周期变化时调用。(如:启动时、每次登录、退出登录、cookie过期)
*
* @param   userId      用户账号id,nil表示未登录、或退出登录后的游客状态
*/
+ (void)setUserId:(NSString *)userId;

/**
* @brief   设置每页拉取的最大新闻数,默认20。
*
* @param   count      最大数量
*/
+ (void)setRcmdPageCount:(NSInteger)count;

/**
* @brief   用户偏好获取
用于根据用户偏好进行精准推荐
*
* @param   behavior    包括:新闻点击、广告点击、分享、收藏、点赞、不喜欢、页面停留时间等。
* @param   targetid    新闻id或广告id。
* @param   from        newsId的来源。SHWFF_NEWSID_SRC_SHUWEN表示newsId是智云CMS中的id,SHWFF_NEWSID_SRC_MEITI表示newsId是媒体自己CMS中的id
* @param   duration    连续型事件的持续时间,如:页面停留时间事件。其他时间传0即可。
* @param   value       事件辅助参数,目前只有“不喜欢“事件的原因。
* @param   args        用户自定义参数。
*/
+ (void)userbehavior:(SHWFF_ONCE_BEHAVIOR)behavior targetid:(NSString *)targetid from:(SHWFF_NEWSID_SOURCE)from duration:(long)duration value:(NSString *)value args:(NSDictionary *)args;

/**
* @brief   用户偏好批量获取
用于根据用户偏好进行精准推荐
*
* @param   behavior    包括:新闻列表页浏览等。
* @param   ids         新闻id数组。
* @param   args        用户自定义参数
*/
+ (void)userbehavior:(SHWFF_BATCH_BEHAVIOR)behavior newsidList:(NSArray <SHWFFUserBehaviorItem *>*)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 settingBuild Options 中的Enable Bitcode 置为 NO

Latest podspec

{
    "name": "SHWRecommendSDK",
    "version": "1.0.9",
    "summary": "iOS u65b0u95fbu5206u53d1u63a8u8350 SDK",
    "homepage": "https://github.com/newsdata/shuwen-recommend-sdk",
    "license": {
        "type": "MIT",
        "file": "LICENSE"
    },
    "authors": {
        "yangyang": "[email protected]"
    },
    "platforms": {
        "ios": "8.0"
    },
    "source": {
        "git": "https://github.com/newsdata/shuwen-recommend-sdk.git",
        "tag": "1.0.9"
    },
    "vendored_frameworks": "SHWRecommendSDK/Classes/SHWRecommend.framework",
    "requires_arc": true,
    "frameworks": [
        "CoreLocation",
        "CoreTelephony",
        "Foundation",
        "JavaScriptCore",
        "UIKit",
        "WebKit",
        "SystemConfiguration",
        "CoreFoundation",
        "Security"
    ],
    "dependencies": {
        "SHWAnalyticsSDK": [
            "~> 1.1.8"
        ]
    }
}

Pin It on Pinterest

Share This