天翼互联平台开发者指南(第三方).doc

天翼互联平台开发者指南 天翼互联平台开发者指南V1.0综合平台开发运营中心2013年12月目 录总则- 3 -1.1 名词术语- 3 -2.天翼互联平台介绍- 4 -3.天翼登录开发流程- 5 -4.天翼登录OAuth2.0 授权机制- 9 -4.1 OAuth2.0简介- 9 -4.2 OAuth2.0开发文档- 11 -5.API能力接口- 20 -5.1 API能力列表- 20 -5.2 SDK开发包- 21 -总则1.1 名词术语名 称描 述天翼帐号天翼帐号以手机号、邮箱和用户作为用户登录网站或移动应用及享受各项服务的统一认证鉴权标识凭证。天翼帐号客户端天翼帐号客户端，主要包括便捷设置天翼帐号，“一号通行“移动应用，个人数据同步与备份，用户个性设置及用户消息通知、天翼帐号能力开放授权等 AppID申请“天翼登录”成功后，分配给网站或移动用户的appid，用来唯一标识网站或移动应用appSecret申请“天翼登录”成功后，分配给网站的 appSecret 。 appSecret 将在“天翼登录”过程中以及网站或移动应用通过API访问/修改受保护的资源时，用来计算签名值，以提高传输过程参数的防篡改性。OpenIDOpenID是网站或移动应用中唯一对应用户身份的标识。根据APPID以及天翼帐号生成（生成规则为按手机号码邮箱用户的高低顺利，如用户有绑定手机号码，即拿appid与手机号码生成），不同的appid下同一个天翼帐号生成的OpenID是不一样的（目前不接受同一个开发者名下的不同应用之间对于同一个用户的OpenID的互通）。 天翼帐号的手机号码、邮箱和用户名默认不对外开放，有特殊需要手工设置开放2. 天翼互联平台介绍2.1.1 平台介绍天翼互联平台为第三方网站（WEB/WAP）或移动应用提供了电信及合作伙伴丰富的能力服务API接口。第三方网站或移动应用接入天翼互联平台后，即可通过调用平台提供的API接口实现用户使用天翼账号登录网站或移动应用功能，且可以获取到天翼帐号的相关信息。第三方合作方接入天翼互联平台后，您将获得：n 海量新用户：用户使用已有的天翼帐号即可登录网站或移动应用，天翼套件一键登录更可减少登录交互操作，大大降低网站或移动应用注册门槛，给网站或移动应用带来海量新用户。n 丰富的特权服务：首次成功登录的用户可免费获的电信手机上网流量、WIFI时长、短信和通话时长等志属特权服务，每月活跃次数达到一定次数可持续性获得赠送。n 丰富的开放API：网站或移动应用通过调用天翼互联平台提供的丰富API接口实现用户信息、电信套餐信息、发免费短信、支付、云空间、189邮箱和云通讯录等功能。2.1.2 目标客户所有的互联网网站和移动应用2.1.3 接入方式天翼互联平台为网站和移动应用提供了丰富便捷的SDK集成包，辅助开发者快速接入天翼登录和API能力调用等功能n API接入方式网站和移动应用均可使用n 网站接入SDK提供JAVA-SDK、PHP-SDK和.NET-SDK等主流开发语言开发集成包n 移动应用接入SDK提供Android-SDK、IOS-SDK和WP7等主流手机平台开发集成包3. 天翼登录开发流程3.1 开发者注册开发者通过天翼互联平台门户以天翼帐号进行登录后，在注册页面提交公司或个人基本资料后。重要提示： 开发者天翼帐号一旦注册不能变更，建议使用公司公共天翼帐号而不是员工私人号码注册，以免遇到员工离职等情况造成不必要的麻烦。 接入申请网站或移动应用接入前，需首先创建网站或移动应用，并获得对应的appid与appSecret，以保证后续流程中可正确对网站或移动应用与天翼帐户进行验证与授权。 开发流程概述对网站或移动应用进行开发，即完成天翼登录功能并正常放置天翼登录按钮，具体开发流程主要包括如下几个步骤：.1 设置天翼登录入口网站或移动应用开发者可以在自己的网站或移动应用首页入口和主要的登录、注册页面上放置“天翼登录”标识（见红色方框标记处）： 网站登录标识 移动应用登录标识.2 用户登录验证和授权1）用户点击按钮之后弹出天翼登录的窗口，在登录窗口中将显示网站或移动应用相关标识信息，如名称以及链接地址等。如果用户已登录“天翼帐号客户端 ”或其它已接入天翼互联平台的网站或移动应用，也可以一键快速登录。2）登录界面右边为用户选择授权允许网站或移动应用访问自己的相关信息（仅在第一次成功登录，以及第一次访问某个未授权的API时会出现授权页），如下图所示：网站登录界面 WAP登录界面 移动应用登录界面授权框中的授权列表由第三方网站或移动应用自行配置，详见scope参数说明。建议控制授权项的数量，只传入必要的接口名称，因为授权项越多，用户越可能拒绝进行任何授权。.3 登录和授权完成后，跳转回网站或移动应用如果用户成功登录并授权，则跳转到指定的回调地址，该回调地址由第三方网站或移动应用自行配置（在上一步的请求中传入），回调地址建议设置为首页或用户中心。.4 获取并存储access token以及openid成功登录后，即可发送请求来获取access token以及openid，这两个参数在调用API访问和修改用户数据时必须传入，网站需自行绑定或存储：（1）access token用来判断用户在本网站上的登录状态，具有3个月有效期，用户再次登录时自动刷新。（2）openid是此网站上唯一对应用户身份的标识，网站可将此ID进行存储便于用户下次登录时辨识其身份，或将其与用户在网站上的原有账号进行绑定。.5 显示用户登录昵称与头像建议网站调用用户信息API接口，在首页或顶部显示用户通过天翼帐号的登录状态，使用户体验一致，包括用户昵称（如没有昵称，）、头像，如下图所示：.6 开发说明天翼登录功能使用国际通用的OAuth2.0协议进行验证与授权，可通过以下方式进行网站或移动应用开发：（1）基于网站，可使用天翼互联平台提供的SDK包，用户体验统一，只需要修改少量代码，不需要理解验证授权流程，需要快速接入天翼登录的网站或移动应用可选用此方法。（2）基于移动应用，可使用天翼互联平台提供的iOS和Android的SDK开发包。如果手机安装了天翼帐号客户端，则启动天翼帐号客户端进行SSO登录。如没有安装，则通过手机系统的浏览器进行登录。登录的流程已经集成在SDK里，建议开发者使用此方法。（3）根据天翼登录OAuth2.0协议，自主开发，此方法自定义程度较高，需要与现有系统进行整合的网站可选用此方法。 使用天翼互联提供的API网站或移动应用上线后，可以使用天翼互联平台提供的丰富的API资源：1、我们提供了各种API给开发者，可以调用这些API来实现需要的功能，使登录用户在网站或移动应用上即可访问和修改受保护的资源。4. 天翼登录OAuth2.0 授权机制4.1 OAuth2.0简介4.1.1 什么是“天翼登录OAuth2.0”n OAuth： OAuth（开放授权）是一个开放标准，允许用户授权第三方网站访问他们存储在另外的服务提供者上的信息，而不需要将用户名和密码提供给第三方网站或分享他们数据的所有内容。n 天翼登录OAuth2.0：对于用户相关的API（例如获取用户信息，电信套餐信息，云空间信息等），为了保护用户数据的安全和隐私，第三方网站或移动应用访问用户数据前都需要显式的向用户征求授权。n 天翼登录OAuth2.0采用OAuth2.0标准协议来进行用户身份验证和获取用户授权。4.1.2 天翼登录OAuth2.0接入方式天翼登录OAuth2.0支持网站接入和移动应用接入。n 网站可通过以下两种方式接入：（1）使用天翼互联平台提供的SDK包，用户体验统一，只需要修改少量代码，不需要理解验证授权流程，需要快速接入天翼登录的网站和移动应用可选用此方法。SDK包括JavaScript，Java，PHP等多个版本的（2）根据天翼登录OAuth2.0协议，自主开发，此方法自定义程度较高，需要与现有系统进行整合的网站和移动应用可选用此方法。n 移动应用开发可通过以下两种方式接入：（1） 使用天翼互联平台提供的iOS，Android等平台的SDK包，用户体验统一，只需要修改少量代码，不需要理解验证授权流程，需要快速接入天翼登录的移动应用可选用此方法。iOS与Android版本的SDK均支持web view与浏览器两种方式，即支持跳转到手机浏览器上进行天翼登录与验证流程，开发者可在SDK包中选择浏览器模式即可，但浏览器方式用户跳跃较大，不建议使用。（2）根据天翼登录OAuth2.0协议，自主开发，此方法自定义程度较高，需要与现有系统进行整合的移动应用可选用此方法。建议移动应用使用webview的方式打开登录页面，登录成功后，获取accesstoken与openid，webview控件关闭，用户体验较好。4.1.3 天翼登录OAuth2.0总体处理流程天翼登录OAuth2.0总体处理流程如下：Step1：申请接入，获取appId和appSecret；Step2：开发应用，进行测试联调；Step3：放置天翼登录按钮；Step4：通过用户登录验证和授权，获取Access Token；Step5：通过Access Token获取用户的openId；Step6：调用API，来请求访问或修改用户授权的资源。4.1.4 天翼登录OAuth2.0开发说明开发者需要根据天翼互联平台提供的UI规范，请求说明，接口说明进行UI和代码的开发。4.2 OAuth2.0开发文档4.2.1 准备工作_OAuth2.0接入天翼登录前，网站或移动应用需首先进行申请，获得对应的appId与appSecret，以保证后续流程中可正确对网站或移动应用与用户进行验证与授权。1、申请appId和appSecret申请appId和appSecret的用途appId：应用的唯一标识。在OAuth2.0认证过程中，appId的值即为oauth_consumer_key的值。appSecret：appId对应的密钥，访问用户资源时用来验证应用的合法性。在OAuth2.0认证过程中，appSecret的值即为oauth_consumer_secret的值。注意:对appId和appSecret信息进行保密，不要随意泄漏。2、保证连接畅通接入天翼登录时，网站或移动应用需要不停的与天翼互联平台进行交互，发送请求和接受响应。1）对于WEB/WAP网站：请在你的服务器上ping ，保证连接畅通。2）移动应用无需此步骤4.2.2 获取Access_Token通过用户验证登录和授权，获取Access Token，为下一步获取用户的openId做准备；同时，Access Token是应用在调用API访问和修改用户数据时必须传入的参数。 网站接入方式获取Access_Tokenn 简介- 网站接入方式使用Authorization_Code获取Access_Token即server-side模式，是OAuth2.0认证的一种模式，又称Web Server Flow；- 适用于需要从web server访问的应用，例如WEB/WAP网站。- 其授权验证流程示意图如下（来源：OAuth2.0协议草案V21的4.1节）需要进行两步：1. 获取Authorization Code；2. 通过Authorization Code获取Access Tokenn 过程详解Step1：获取Authorization Code请求地址：/api /oauth2/authorize.do请求方法：GET请求参数请包含如下内容：参数是否必须含义responseType必须授权类型，此值固定为“code”。clientId必须申请天翼登录成功后，分配给应用的appId。redirectUri必须成功授权后的回调地址，必须是注册appid时填写的主域名下的地址，建议设置为网站首页或网站的用户中心。注意需要将url进行URLEncode。state必须client端的状态值。用于第三方应用防止CSRF攻击，成功授权后回调时会原样带回。请务必严格按照流程检查用户与state参数状态的绑定。wap可选用于展示的样式。不传则默认展示为PC下的样式。如果传入“2”，则展示为wap2.0的样式。返回参数：字段标识说明数据类型长度(字节)可空state原始的state值String32Ncode用来换取accessToken的授权码，有效期为10分钟，成功时返回String64NopenId用户统一标识，可以唯一标识一个用户String100N返回说明：1. 如果用户成功登录并授权，则会跳转到指定的回调地址，并在redirectUri地址后带上Authorization Code和原始的state值。如：PC网站：http:/ redirectUri?code=9A5F*06AF&state=test&openId=1564961注意：此code会在10分钟内过期。Step2：通过Authorization Code获取Access Token请求地址：/api/oauth2/accessToken.do请求方法：GET请求参数：请求参数请包含如下内容：参数是否必须含义grantType必须授权类型，在本步骤中，此值为“authorization_code”。clientId必须申请天翼登录成功后，分配给网站的appId。clientSecret必须申请天翼登录成功后，分配给网站的appSecret。code必须上一步返回的authorization code。如果用户成功登录并授权，则会跳转到指定的回调地址，并在URL中带上Authorization Code。例如，回调地址为/my.php，则跳转到：/my.php?code=520DD95263C1CFEA087*注意此code会在10分钟内过期。redirectUri必须与上面一步中传入的redirectUri保持一致。format可选数据返回格式xml/json，默认json返回参数：字段标识说明数据类型长度(字节)可空result返回码。0-成功，非0失败Int4NaccessToken授权令牌，成功时有值String100NexpiresIn该access token的有效期，单位为秒，成功时有值LongNrefreshToken刷新token，成功时有值String100Nscopetoken对应的授权能力代码列表，格式如code1,code2,code3String256Nmsg错误信息，在result!=0的情况下有值String256Y返回说明：如果成功返回，即可在返回包中获取到Access Token。 如：Xml示例： 0360012800138000 getUserInfo,getUserInfo1Json示例：Content-type: text/html; charset=utf-8“result”:0,“accessToken”:”,“expiresIn”:3600,“refreshToken”:”12800138000”,“ scope”:“getUserInfo,getUserInfo1” 通过刷新token方式获取access tokenAccess_Token的有效期默认是90天，过期后需要用户重新授权才能获得新的Access_Token。本方式可以实现授权自动续期，避免要求用户再次授权的操作，提升用户体验。请求地址：/api/oauth2/accessToken.do请求方法：GET请求参数：请求参数请包含如下内容：参数是否必须含义grantType必须授权类型，在本步骤中，此值为“refresh_token”。clientId必须申请天翼登录成功后，分配给网站的appid。clientSecret必须申请天翼登录成功后，分配给网站的appkey。refreshToken必须在Step2中，返回的refres_token。format可选数据返回格式xml/json，默认json返回参数：字段标识说明数据类型长度(字节)可空result返回码。0-成功，非0失败Int4NaccessToken授权令牌，成功时有值String64NexpiresIn该access token的有效期，单位为秒，成功时有值LongNrefreshToken刷新token，成功时有值String64Nmsg错误信息，在result!=0的情况下有值String100Y返回说明：如果成功返回，即可在返回包中获取到Access Token。 如：Xml示例： 0360023800238000Json示例：Content-type: text/html; charset=utf-8“result”:0,“accessToken”:”,“ refreshToken”:” 23800238000”,“expiresIn”:36004.2.3 API调用说明 获取到Access Token和openId后，可通过调用API来实现网站或移动应用展现用户信息、电信套餐信息、发免费短信、支付、云空间、189邮箱和云通讯录等功能5. API能力接口5.1 API能力列表能力分类能力描述能力分项接口是否需要申请接口权限用户信息接口提供天翼帐号的相关用户信息，如昵称、用户头像、性别、所在地、签名等基础信息，此能力为默认授权提供昵称getUserInfo.do不需要用户头像性别所在地签名电信用户套餐信息接口提供用户的电信套餐使用情况（包含话费、上网流量、短彩信、WIFI时长、通话时长、积分和缴费记录等）的总量和剩余量的信息查询电信用户套餐使用情况（包含上网流量、短彩信、WIFI时长和通话时长等）的总量、使用量和剩余量待推出需要话费信息查询（实时话费、实时金额、欠费金额、帐户话费和帐户余额）待推出需要历史账单查询待推出需要缴费记录查询待推出需要积分情况查询待推出不需要已订套餐查询待推出需要已订购增值业务查询待推出需要短信能力接口提供向用户免费发短信服务（每用户每月有100条免费短信额度）发送免费Web短信待推出需要发送免费web短信（横向菜单）待推出发送免费web短信（纵向菜单）待推出支付能力接口提供WEB和手机客户端支付能力财付通一键支付待推出需要财付通包月支付待推出189邮箱接口提供发邮件、获取邮件列表/邮件数信息、回复邮件等服务189邮箱帐号信息查询待推出需要查询邮件数待推出不需要流量币接口提供流量宝的流量币查询及赠送服务流量币查询待推出需要流量币赠送待推出不需要5.2 SDK开发包天翼互联平台为广大开发者提供了以下SDK集成开发包，辅助开发者快速接入天翼登录和使用API能力等功能5.2.1 SDK for 网站接入提供JAVA-SDK、PHP-SDK和.NET-SDK等主流开发语言开发集成包5.2.2 SDK for 移动应用接入提供Android-SDK、IOS-SDK和WP7等主流手机平台开发集成包6. 附录：API接口使用说明6.1 查询用户信息应用场景移动终端应用通过调用该接口来获取用户的属性信息。接口定义接口名称getUserInfo.do接口描述提供查询用户属性信息的能力承载协议HTTP承载网络CN2请求方式POST/GET数据格式json/xml约束用户已登陆接口URL