星图按转化线索回传对接思路与示例

一、什么是星图？
二、什么是线索转化？
三、对接中的一些疑问？
四、如何对接开发？
五、星图侧如何联调测试？

一、什么是星图？

抖音星图是抖音电商蓝图下，为品牌方、MCN公司和明星/达人服务并收取分成，在这可以实现订单接收、签约管理、项目汇总、数据查看的平台，当下比较多的使用就是一些MCN公司为旗下艺人揽活的。

商户可以在平台按照需求发布任务，那么任务有分一口价任务、按转化结算的任务，本文要涵盖的是对接按线索转化类任务。

二、什么是线索转化？

线索转化的逻辑就是：星图随巨量广告投放的时候，会添加埋点参数，根据需求对接并追踪埋点参数，在符合逻辑的业务节点回调星图，标记为一个线索。

三、对接中的一些疑问？

对接过程中遇到过很多问题，比如：

Q:对于混杂的文档，都没讲全，版本以及更新时间不一致，如何获取的最新版本对接文档？
A:联系直客，直客提供的文档下可以提问，会有星图值班人员回复，加上飞书后可以更仔细得咨询。
不过直客也不一定靠谱，还是最终最好找到星图侧的人。
这是我当前获取到最新的对接文档：https://bytedance.feishu.cn/docx/WOQRd9htbohMfrxDLxrctbznn5g （这个文档一开始看没有权限复制有点坑，要申请加白才能复制）

Q：文档上说的转化ID是巨量老版本转化追踪吗？
A：是的。

Q：老版本转化追踪都已经迁移切换，都不推荐使用，无人技术支撑了，怎么办？
A：星图回传转化ID如果已经不能在巨量平台完成联调测试，那么请直客加白（或星图值班号），加白后可以无需转化ID。

Q：星图的回传会影响巨量的回传吗？
A：不会，他们回传的clickid类型不同，注意区分即可。

Q：星图回传接口与巨量回传接口是需要相同还是可以不同？
A：星图与巨量的回传可以理解为完全不相干的两个流程，可能就是老接口一致会给人混淆。
巨量当前老版本转化追踪不提供技术支撑了(工单即使反馈问题也解决不了)，那必然就是建议使用新接口进行回传。巨量的回传为了优化投流策略，效果追踪。
星图全部都是要求老接口的，那么就是走老接口回传。星图的回传是为了线索类结算。

Q：巨量旧版本转化追踪进行联调，提示“该用户id不存在”
A：请直客对你们的广告账户加白后就不需要依赖填写转化ID了，也就不需要做这个联调了。这个错误提示基本就是不允许进行旧版本的联调测试了，巨量侧不支持了。
在这里插入图片描述

通过以上这些含老血踩出来的经验，希望能给你理清一些思路。
那么下面就是用巨量转化追踪老接口，根据星图的需求，回传指标数据即可。
以下是根据小程序、落地页投放，API回传，进行表单提交线索转化结算的流程（如果是应用类SDK回传的再自行研究吧）。

四、如何对接开发？

通常为打开落地页/小程序时，落地页url上携带的clickid参数（这是最核心的，可能部分投放还带有其它参数），可将clickid参数放在如下demo中的callback=xxx中，完成数据回传。参数埋点是如何获取，并传递到后端服务的，这边就不详细描述了。

这个clickid在实际投放巨量广告的时候能够看到，巨量绑定的clickid是“E…”开头的，需要注意星图绑定的clickid是“B…”开头的。所以在做巨量回传和星图回传的时候注意区分clickid。

按照以上思路呢，基本已经获取到了星图侧传递过来的clickid了，那么下面看如何回传与测试。

继续参考这个文档：https://bytedance.feishu.cn/docx/WOQRd9htbohMfrxDLxrctbznn5g

回传事件类型:

event_type=0，表示激活
event_type=1，表示注册
event_type=2，表示付费，对于按付费分佣结算（CPS），必须回传付费金额，可在props中增加pay_amount参数，单位为分，需通过unicode编码
event_type=3，表示表单提交，投稿任务需回传加密的手机号进行结算，因此需增加phone_num参数。注意手机号为高敏感信息，有单独密钥
event_type=72，表示无效线索，可通过 props 的 invalid_type 字段回传无效线索的类型，需对props进行encode，并放到URL中
- repeat_form_submission，重复提交表单（同地址/同手机号/同身份证重复申请办理）。判断规则：30天内同地址/同手机号/同身份证重复申请办理2次及以上的表单
- identity_verification，身份信息校验不匹配。判断规则：三方平台国证通判断身份证与姓名不匹配的表单
- wrong_address，地址乱填。判断规则：字数较少（如6字以内）、明显为无效地址的表单
- wrong_phone_number，空号/联系电话虚假。判断规则：通过三方平台外呼判断手机为空号的表单
- address_verification，IP地址与收货地址不一致。判断规则：通过ip地址与收货地址进行校验后，匹配不成功的表单
- map_verification，地图校验不一致。判断规则：通过高德地图系统校验，匹配不成功的表单

# 线索场景
https://ad.oceanengine.com/track/activate/?callback=xxxx&event_type=3&phone_num=xxxx

# 激活场景
https://ad.oceanengine.com/track/activate/?callback=xxxx&event_type=0

# 注册场景
https://ad.oceanengine.com/track/activate/?callback=xxxx&event_type=1

# 付费场景
https://ad.oceanengine.com/track/activate/?callback=xxxx&event_type=2&props=%7B%22pay_amount%22:%20%221000%22%7D

测试采用表单数据回传方式，那么需要增加phone_num字段且需要加密。

java方式，以下每次输出结果均会不同

public static void main(String[] args) throws Exception {
    String encryptNum = generatePhoneNum("13312345678");
}

private static String generatePhoneNum(String phoneNum) throws Exception {
    String publicKeyStr = "-----BEGIN PUBLIC KEY-----\n" +
            "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCmnVrcCkHV8b+2BaMSC95DY0z9\n" +
            "9B7MgFoHMxXaZn0k6fvUXJTgxXtYleGFdoifHSVsrJIB0P1V4hazTIyDLnHGFOCp\n" +
            "UnYkLE2L8M/l0msAiKmShlxQAPB9IBNLOLFcp3qubLjfGGB1xfsDXHY9dAxYY8XC\n" +
            "edrYgXwkAoi3/dL+UQIDAQAB\n" +
            "-----END PUBLIC KEY-----";
    String publicKeyPem = publicKeyStr.replace("-----BEGIN PUBLIC KEY-----", "")
            .replaceAll("\\n", "")
            .replace("-----END PUBLIC KEY-----", "");
    byte[] keyContentAsBytes = Base64.getDecoder().decode(publicKeyPem);
    KeyFactory fact = KeyFactory.getInstance("RSA");
    X509EncodedKeySpec pubKeySpec = new X509EncodedKeySpec(keyContentAsBytes);
    PublicKey publicKey = fact.generatePublic(pubKeySpec);
    String phoneNumAfterEncrypt = encrypt(phoneNum, Base64.getEncoder().encodeToString(publicKey.getEncoded()));
    System.out.println(phoneNumAfterEncrypt);
    String encodePhoneNumAfterEncrypt = URLEncoder.encode(phoneNumAfterEncrypt, StandardCharsets.UTF_8.toString());
     System.out.println(encodePhoneNumAfterEncrypt);
    return encodePhoneNumAfterEncrypt;
}

public static String encrypt(String str, String publicKey) throws Exception {
    byte[] decoded = Base64.getDecoder().decode(publicKey);
    RSAPublicKey pubKey = (RSAPublicKey) KeyFactory.getInstance("RSA").generatePublic(new X509EncodedKeySpec(decoded));
    Cipher cipher = Cipher.getInstance("RSA");
    cipher.init(Cipher.ENCRYPT_MODE, pubKey);
    return Base64.getEncoder().encodeToString(cipher.doFinal(str.getBytes(StandardCharsets.UTF_8)));
}

python方式，版本使用3.7，官方提供demo未描述python版本无法跑通，以下每次输出结果均会不同。

# python3.7环境下安装：
# pip install pycryptodome --user

from Cryptodome.PublicKey import RSA
from Cryptodome.Cipher import PKCS1_v1_5 as PKCS1_cipher
import base64

def gen_num(phone_num):
    # 这个PEM是有格式的，不要改动，否则报错：ValueError: Not a valid PEM pre boundary
    pub_key = RSA.importKey("""-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCmnVrcCkHV8b+2BaMSC95DY0z9
9B7MgFoHMxXaZn0k6fvUXJTgxXtYleGFdoifHSVsrJIB0P1V4hazTIyDLnHGFOCp
UnYkLE2L8M/l0msAiKmShlxQAPB9IBNLOLFcp3qubLjfGGB1xfsDXHY9dAxYY8XC
edrYgXwkAoi3/dL+UQIDAQAB
-----END PUBLIC KEY-----""")
    cipher = PKCS1_cipher.new(pub_key)
    rsa_text = base64.b64encode(cipher.encrypt(bytes(phone_num.encode("utf8"))))
    return rsa_text.decode('utf-8')

if __name__=='__main__':
    print(gen_num("13312345678")) # RhLLAnzd7wQx0w5T+5Lzn6gie+FlVrDfP3dqohxDn/OVsDmEiqbgtFDoIC6/ILY3TDgH3pmeqUy1QIh9X1xLPbiYQKe4mnujeAyh+G5Q7SvGb7GJLLdCsI2akCnv0joOuR6CxbGQ3qrWxhR7YjNWztqTp8KCVnO+gaYo3Qd7ndc=

五、星图侧如何联调测试？

联调工具只能测试落地页，可以用落地页测试来确认接口加解密逻辑的正确性。在星图管理后台，在我的任务 -> 工具 -> 分析工具 -> 监测联调 -> 线索回传联调。

填入落地页链接
点击落地页链接，在星图页面内直接跳转
转化回传数据至指定地址，这个xingtu域名的是测试地址，正式的采用ad巨量的旧转化回传地址

回传需要除了需要区分出B开头的clickid，此外还需要注意:

callback需要base64后加上star-
event_type必须传3
phone_num是加密后的留资手机号，phone_num需要转义(这一步上面demo中已经包含)

确保123步都操作完成后，点击“查看联调结果”
若显示“成功收到1条线索，解析成功1条线索”，即代表流程畅通，可正常在星图下单开始任务

在这里插入图片描述

正式回传样例

https://ad.oceanengine.com/track/activate/?callback=star-9e9adf4383d907c42921d3ae539370f2&event_type=3&phone_num=ChOInt8EQsQqIi8FAcstJraXIkdQvJ2jpWOQCsNI7wDaxQtggHzVOLoSGtHG25SN9CF5svCHpyQbR/ha2msOLZl1rx4PYas3hdsmu7mB9phCr8G+Q+lSaUcl30kc5SabRgJDHHEXCJ5RAkd5FHSttWGHl8ZgbgGxeIH86+Cs4Vo=

接收成功的返回值：

{
 "code":0,
 "ret":0,
 "msg":"success"
}