05/15/2024 15:19:52

好友关系链

一、同玩好友(不包含自己)

手Q/微信渠道拉取好友关系链需要到平台侧申请关系链权限，为了方便业务接入，飞鹰集成了快速申请权限的通道，飞鹰系统 -> 左侧菜单 MSDK接入->特殊权限申请->手Q关系链/微信关系链。
目前支持渠道：QQ、WeChat、Facebook、garena、VK、steam。

1.1 接口名

/v2/friend/friend_list

1.2 请求参数

1.3 返回参数

lists说明

lists {
    string openid;          // 用户标识
    string user_name;       // 昵称
    int gender;             // 性别，未定义：0，男：1，女：2。手Q渠道固定返回 0，微信不支持该字段
    string picture_url;     // QQ/微信好友头像 URL
    string country;         // 国家
    string provice;         // 省份
    string city;            // 城市，微信不支持该字段
    string language;        // 语言
    string nick_name;       //（仅微信支持）好友在社交渠道的昵称，先确认字段存在后再取值，因为权限正常且微信正常返回昵称时该字段才存在
    string friend_remark;   //（仅微信支持）好友备注名，先确认字段存在后再取值，因为权限正常且微信正常返回昵称时该字段才存在
}

特别说明

• user_name 会随时根据策略进行管控，如有明确使用微信备注名的需求，请务必使用 friend_remark 来获取；新接入业务 user_name，默认只返回昵称；
• 针对新业务，昵称应该使用 nick_name 字段，如果需要好友备注，需要走申请报备流程，确认好友备注使用的合规性再使用 friend_remark 字段；
• QQ 好友头像 URL，必须在 URL 后追加参数 /40 或 /100。这样可以分别获得 <40*40>(/40) 或 <100*100>(/100) 规格的图片；
  
• 微信好友头像 URL，必须在 URL 后追加参数 /0、/46、/64、/96 或 /132。这样可以分别获得原始图片(/0)、<46*46>(/46)、<64*64>(/64)、<96*96>(/96) 或 <132*132>(/132) 规格的图片；
  
• 海外渠道如 Facebook 为了出海游戏符合 GDPR 规范，好友信息的性别信息固定返回 0；
  
• 没有同玩好友时，回包中没有 lists 字段是正常现象；

1.4 请求示例

微信渠道

• 请求

    {
        "openid": "13601369187816917176",
        "token": "61_nTO2IrYUm4KTM58tuZYZR8wZMbjyDJWndI_AMzuIKjAOGDobd94FtNLaiH8KmB774Q40xDo14hjnmHi_mZocsuACKV3GVps7gPXr-glx4Ts"
    }
  

• 回包

    {
        "ret": 0,
        "msg": "",
        "lists": [
            {
                "user_name": "zzz",
                "picture_url": "https://wx.qlogo.cn/mmhead/No0JxNE4LEUcXM5dmgJcjEadU8jllM45SGtOHxsmiafM",
                "provice": "",
                "openid": "6292984005760995448",
                "nick_name": "Σ(￣。￣ノ)ノ",
                "friend_remark": "小张"
            },
            {
                "user_name": "小佳",
                "picture_url": "https://wx.qlogo.cn/mmhead/Zc9yUpJNc2MVN3IzgUtL9BsfA09pp4MSaaib8nSDb03M",
                "provice": "",
                "openid": "18182179939911361117",
                "nick_name": "小佳"
            }
        ],
        "seq": "1664333165-3965425163-019804-0315511573"
    }
  

手Q渠道

• 请求

    {
        "openid":"4724195171999796436",
        "token":"27A50B44430AAD6BFFBE09BA875E48BB"
    }
  

• 回包

    {
        "ret": 0,
        "msg": "",
        "lists": [
            {
                "user_name": "小张",
                "gender": 0,
                "picture_url": "https://q.qlogo.cn/qqapp/1106977030/A7DB20EFF6DD4A617367B71186DB33A6/",
                "openid": "14882639338379730531"
            },
            {
                "user_name": "小佳",
                "gender": 0,
                "picture_url": "https://thirdqq.qlogo.cn/qqopen/ZdvYp9s7k6qJuCiaNlJR3hT5vtL0rJxiclJ814gxnmuKYXv0xs04j1WWUoKX1u1MlE/",
                "openid": "15991060247728890761"
            }
        ],
        "is_lost": 0,
        "seq": "1664333315-0844862987-022347-0109203549"
    }
  

二、获取未注册手Q好友/微信密友

2.1 接口名

/v2/friend/recall_friends_list

2.2 接口说明

重要：获取未注册手Q好友/微信密友（关系链推广员能力），在游戏内调用时会获取未经授权的用户数据，经《个人信息保护法》评估须进行改造，请已接入使用的项目组关注。未接入的游戏暂停接入申请。

① 平台改造方案：在游戏内该接口将返回“无推荐好友”的空数据，请项目组关注用户界面处理，必要时需隐藏游戏内使用未注册密友/推广员的界面入口。

② 生效时间：2021年11月5日 18:00 前。

手Q平台公告详情可咨询 qqconnecthelper(QQ互联及登录咨询);
微信平台公告详情可咨询 wxgame(微信游戏助手) 或参见 https://mmgame.oa.com/index.html#/announce/detail?id=174 。

2.3 请求参数

2.4 返回参数

1）微信 result 结构

2）手Q result 结构

注意：friend_list 列表中每个对象包含 sopenid、head_img_url、nick_name 三个字段

2.5 请求示例

# 微信
curl -X POST -H 'Content-Type: application/json' 'https://hktest.itop.qq.com/v2/friend/recall_friends_list?channelid=1&conn=&gameid=12&os=1&seq=&source=0&ts=1570764309&version=2.0&sig=cae2c68c247db13d0d9e111f90f0eb54' -d '{"openid":"3505996091832136773","token":"26_cUcJse2lEvZP9SojX5Oc-EKdaFV96i-sMOOCL3OB_fMSiwmq6wjC4e3tOj_zW7f8U3j8BAqBjwNaJPdR70U76B-hRkkgs1CMcVhLLiVj86U","task_id":0}'

{
    "msg": "success",
    "result": {
        "friend_list": [
            {
                "sopenid": "sHlap1bakvTsj1fyeeWxPoIW5OiY",
                "head_img_url": "http://wx.qlogo.cn/mmopen/vi_32/298Iynvq8598KfjWKRxHX0w2P1icnoE1mnj6BlOBicEOAoG6qbl6oD6Csumiaq2LFIsiat5ZZAsN95SRDULfoiaob4g/0",
                "nick_name": "弓长月半月半"
            },
            {
                "sopenid": "sHlap1V3R7QDESg-WgyRfXI5ZKcI",
                "head_img_url": "http://wx.qlogo.cn/mmopen/vi_32/Q0j4TwGTfTIAmxdv26icib4TayhbZqqdJ49Zvwicukf8vJw6zCgPdDAYxMEG37tkkmg54Y8zrObeFCKpKMcRaMGzg/0",
                "nick_name": "林"
            }
        ],
        "model_id": 0,
        "send_list": []
    },
    "ret": 0,
    "seq": "1570770148-0268717065-046971-0000003701"
}

# 手Q
curl -X POST -H 'Content-Type: application/json' 'https://hktest.itop.qq.com/v2/friend/recall_friends_list?cgsource=cloudgame&channelid=2&conn=&gameid=12&os=1&seq=&source=0&ts=1572523399&version=2.0&sig=a8598291194154e79cb6b7c0a6f40e55' -d '{"token":"D46EF700A328F58231FF69045A54C91D","openid":"15879468368890148661","count":20}'

{
    "msg": "success",
    "ret": 0,
    "result": {
        "friend_list": [
            {
                "sopenid": "ChBBXeAbRjqUbDa8zZ8K_A1oNBKBAWK9mxgNDNwJIxBYd6IWho2aWtjfbWqkjpi7",
                "nick_name": "禾苗苗芋头",
                "head_img_url": "https://thirdqq.qlogo.cn/qqapp/1106977030/B784C3A8411A406546E40DCD9D898635/100"
            },
            {
                "sopenid": "NYcNfgzl7EIk5d96VCJOYJtHI3wYf0qUOqG5X8ilZGW8lMlr2v0QtXUkcXQrH4d3",
                "nick_name": "运营开发-蒋慧强",
                "head_img_url": "https://thirdqq.qlogo.cn/qqapp/1106977030/255E40A981DF206E75975A7440098C1D/100"
            },
            {
                "sopenid": "ajOYNtR74_zxjXaKF6h-0GuOCNhXuCrtGS_ADdx3D_V-9Jb_wsQOvYbHjUXZaCUs",
                "nick_name": "纳斯达．α",
                "head_img_url": "https://thirdqq.qlogo.cn/qqapp/1106977030/DF5130F8023DFE197B121346B10EB9FA/100"
            },
            {
                "sopenid": "P61CN9sYPuDO05-ydiefCUGYKGzPE8avgAhhMVlUBQVu7-VAq1CclagM2qo5f_R8",
                "nick_name": "王志波",
                "head_img_url": "https://thirdqq.qlogo.cn/qqapp/1106977030/56ED3920969AFAD056EB83A323B1155D/100"
            }
        ]
    },
    "seq": "1572525472-0016777343-022540-0000000191"
}

特别说明

• 调用微信密友接口需要申请权限，微信密友文档参考：https://mmgame.oa.com/doc/#/article/144；
• 权限申请流程：
  1.产品参考”微信密友文档“中模板发送邮件申请；
  2.开发发起线上申请（https://weixin.oa.com/open_broker/ ），需要双方总监审批通过；
  3.测试环境调用接口当前需要联系@mmgame_helper(微信游戏开发助手)进行 appid 同步(正式环境绑定需要游戏过了 pr1 之后联系协同操作）；

三、获取 sopenid(仅QQ、微信渠道支持)

3.1 接口名

/v2/profile/get_sopenid

3.2 请求参数

3.3 返回参数

3.4 请求示例

# 微信
curl -X POST -H 'Content-Type: application/json' 'https://test.itop.qq.com/v2/profile/get_sopenid?channelid=1&conn=&gameid=12&os=1&seq=&source=0&ts=1572523399&version=2.0&sig=b7724e08bc2627576391104c340df9bd' -d '{"token":"27_l7XUrQiS8dyqIA4vGGqfjJsVwVBl0EKl30kaArFK6ALSPRXseyJsDw2qZDd6Hl6UgvsLhe5cLEL2aJ5_j5Od1JrEaFwMOIOQ9aAd578sfyQ","openid":"3505996091832136773"}'

{
    "ret": 0,
    "msg": "success",
    "sopenid": "sHlap1b2ZKIs92noWooBci31u9Y8",
    "seq": "1572525723-0016777343-022546-0000000075"
}

# 手Q
curl -X POST -H 'Content-Type: application/json' 'https://test.itop.qq.com/v2/profile/get_sopenid?channelid=2&conn=&gameid=12&os=1&seq=&source=0&ts=1572523399&version=2.0&sig=074133c7f08e4b0320aee6584e244e49' -d '{"token":"D46EF700A328F58231FF69045A54C91D","openid":"15879468368890148661"}'

{
    "ret": 0,
    "msg": "success",
    "sopenid": "ikrjDgPqEUPTY_jnBKx9w5NZAkOimlyv-Tzl2Cj0gEFCtDHY_KjzRQBD9CuufGrM",
    "seq": "1572525777-0016777343-022540-0000000192"
}

四、分享(仅QQ渠道支持)

4.1 接口名

/v2/friend/share

4.2 接入说明

该接口平台侧已不再接受游戏接入，接入 ARK 后端分享，如有特殊需求请联系手Q游戏中心对接（已接入游戏可继续使用）。

4.3 接口说明

手Q后端分享，可通过 C2C 收到分享的结构化消息 / ARK消息（在绿洲平台申请 sceneid 发送消息，调用 /v2/friend/ark_share ）。另外，也可以通过“QQ手游”公众号收到分享消息，但需提前关注该公众号。
分享的内容只有手机 QQ 上才可以看到，PC QQ 上看不到。

收发限制：
1、结构化消息
同一对号码发送接收，互动次数是一天一次。
接收方，每天最多接收 5 条，每周最多接收 20 条。
发送方，每天发给不同用户，最多发送 10 条，每周最多发送 40 条。
2、ark消息
接收方，每天最多接收5条，接收自同一个人最多3条。
发送方，每天最多30条，每周最多100条。

通过"QQ手游"公众号接收的消息，平台侧会延时下发，于每日固定三个时间段（当前是每天12点，20点，22点）通过公众号下发，单用户每天最多收到3条公众号消息。

4.4 请求参数

channel_info 字段

4.5 请求返回

4.6 请求示例

• 请求URL

    http://hktest.itop.qq.com/v2/friend/share?channelid=2&gameid=11&os=1&seq=123&ts=1530792639&version=&sig=f544c40d50c28f4094aabd2d6638a9a3
  

• 请求Body

    {
        "openid": "4724195171999796436",
        "token": "27A50B44430AAD6BFFBE09BA875E48BB",
        "fopenid": "4124157778415485412",
        "title": "test_share",
        "desc": "nothing to share",
        "link": "",
        "image_url": "http://mat1.gtimg.com/www/images/qq2012/erweimaNewsPic.png",
        "game_tag": "",
        "type": 20000,
        "channel_info": {
            "target_url": "http://mat1.gtimg.com/www/images/qq2012/erweimaNewsPic.png",
            "dst": 1001,
            "src": 0,
            "flag": 1
        }
    }
  

• 响应

    {
        "ret": 0,
        "msg": "success!",
        "seq": "123"
    }
  

五、手Q ARK 后端分享(仅QQ渠道支持)

5.1 接口名

/v2/friend/ark_share

5.2 接入说明

手Q ARK分享服务接口提供了ARK消息 C2C 分享能力（分享消息给手机QQ好友，在好友会话框中显示），在绿洲平台申请 sceneid，发送 ARK 类型消息。以下流程均需要联系腾讯对接人：
（1）接入方联系 QQ平台运营 录入信息，QQ平台运营 将信息提交给平台流程组录入；
（2）接口接入完成后验证分享是否成功。

5.3 接口说明

1.分享的内容只有手机QQ上才可看到，PC QQ上看不到。
2.收发限制：
接收方，每天最多接收5条，接收自同一个人最多3条。
发送方，每天最多30条，每周最多100条。

5.4 请求参数

说明：
extraJson 在手Q侧申请接入ARK分享流程完成后会拿到该参数 , 使用时需要将json串的注释和空白符去掉，压缩成一个字符串后再进行url encode加密。

5.5 请求返回

5.6 请求示例

• 请求URL

    https://itop.qq.com/v2/friend/ark_share?channelid=2&conn=&gameid=12&os=1&seq=1111-001&source=1&ts=1605081818&version=2.0&sig=62993d6c7f03f3e5c24fe5bb7ab06091
  

• 请求Body

   {
     "openid": "6703731585054734300",
    "token": "17DD31B2CC12B2A078B8CE4A7333B7FA",
    "fopenid": "14719294144616908484",
    "extra": "%7B%22app%22%3A%22com.tencent.gamecenter.qqsy%22%2C%22view%22%3A%22picView2%22%2C%22desc%22%3A%22%E6%B8%B8%E6%88%8F%E5%88%86%E4%BA%AB%22%2C%22ver%22%3A%221.0.0.1%22%2C%22config%22%3A%7B%22forward%22%3A0%2C%22type%22%3A%22normal%22%7D%2C%22meta%22%3A%7B%22shareData%22%3A%7B%22appid%22%3A%221109719108%22%2C%22openId%22%3A%22%22%2C%22scene%22%3A%22446%22%2C%22url%22%3A%22%22%7D%7D%7D"
   }
  

• 响应

    {
        "ret": 0,
        "msg": "success!",
        "seq": "1594899989-0268717065-054062-0000016317"
    }
  

六、手Q ARK 分享签名生成接口(仅QQ渠道支持)

6.1 接口名

/v2/friend/ark_sign

6.2 接口说明

【注意】业务正式发布前请联系 MSDK助手 评估修改 OIDB 单据频率。

6.3 请求参数

6.4 请求返回

6.5 请求示例

• 请求URL

    https://dev.itop.qq.com/v2/friend/ark_sign?channelid=2&conn=&gameid=12&os=1&seq=&source=0&ts=1692601073&version=2.0&sig=fcd4ef7647b1211af5edfe7c9ad26b02
  

• 请求Body

   {
    "openid": "12629992397987394692",
    "token": "123123",
    "extra": "{\"app\":\"com.tencent.channel.share\",\"prompt\":\"[分享链接]Loading...\",\"meta\":{\"detail\":{\"origin\":\"分享链接\",\"title\":\"Loading...\",\"desc\":\"Level up your coding skills and quickly land a job. This is the best place to expand your knowledge and get prepared for your next interview.\",\"img\":\"https://qq.ugcimg.cn/v1/gpvjqfbrr4fbajrkhade6q8rum44amkp1gt5iaqi4n0r5o6hf4t6inmtuieq9f8hufb3f45k0ibus7htmnr12tih5n14b75954jqvs0/goeub8be9seqoorm568262dnoo\",\"link\":\"https://leetcode.com/problems/word-ladder/\"}},\"config\":{\"ctime\":1629030272,\"autosize\":1,\"forward\":1},\"view\":\"albumAddPic\",\"ver\":\"1.0.0.1\"}"
    }
  

• 响应

    {
    "ret": 0,
    "msg": "success!",
    "data": "{\"app\":\"com.tencent.channel.share\",\"config\":{\"autosize\":1,\"ctime\":1629030272,\"forward\":1,\"token\":\"d610fd3b4247fc8d362473aeb2282491\"},\"meta\":{\"detail\":{\"desc\":\"Level up your coding skills and quickly land a job. This is the best place to expand your knowledge and get prepared for your next interview.\",\"img\":\"https://qq.ugcimg.cn/v1/gpvjqfbrr4fbajrkhade6q8rum44amkp1gt5iaqi4n0r5o6hf4t6inmtuieq9f8hufb3f45k0ibus7htmnr12tih5n14b75954jqvs0/goeub8be9seqoorm568262dnoo\",\"link\":\"https://leetcode.com/problems/word-ladder/\",\"origin\":\"分享链接\",\"title\":\"Loading...\"}},\"prompt\":\"[分享链接]Loading...\",\"ver\":\"1.0.0.1\",\"view\":\"albumAddPic\"}\n",
    "seq": "1692604361-1415414537-022139-0000160877"
    }