一、 新定向总体介绍

定向设置前需要了解每种新定向的类型，可通过以下对照表获取，也可以通过接口获取当前用户有权使用的新定向类型全集，或者根据Enum获取全局新定向。

• 获取当前客户有权使用的新定向类型：taobao.zuanshi.banner.upgrade.target.find

• 获取全局可使用的新定向类型：

com.taobao.ad.zuanshi.service.top.upgrade.crowd.TargetTypeEnum

定向名称	targetType	定向描述	Enum
通投	0	全网人群	ALL
相似店铺定向	701	相似店铺（即类目相似）覆盖的人群	SHOP_COLLECTION
访客定向	700	系统优化之后的指定店铺访问人群	SHOP_VISITOR
相似宝贝定向	702	针对选择的标地宝贝，系统挑选出相似（类目等相关度）宝贝的覆盖人群	LIKE_SIMILAR_ITEM
内容活跃用户定向	710	针对内容化场景，系统挑选出活跃（近期有过互动等）的人群	ACTIVE_FANS
内容领域金牌达人定向	712	针对选择的行业，网红达人所覆盖的用户（与网红近期有互动等）	GOLDEN_EXPERT_FANS
内容形式偏好定向	713	针对选择的渠道，系统挑选出更偏爱（时间窗内，访问频次等）对应渠道的用户	CONTENT_FORM_FANS
明星偏好定向	720	针对选择的明星，系统挑选出更偏爱（时间窗内，关注频次等）他们的用户	SUPER_STAR
文娱节目定向	721	针对选择的娱乐节目，系统挑选出更偏爱（时间窗内，观看次数及时长等）他们的用户	ENTERTAINMENT_PROGRAM
淘宝生活研究所定向	722	淘宝生活研究所对应的人群	CROWD_TRAIT
叶子类目偏好定向	723	针对所选择的叶子类目，系统挑选出更偏爱（时间窗内，访问频次、成交概率等）的用户	LEAF_CATEGORY
商品属性定向	724	针对所选择的商品属性，系统挑选出更适合（时间窗内，成交及浏览概率等）的用户	PRODUCT_STYLE
商品风格定向	725	针对所选择的商品风格，系统挑选出更适合（时间窗内，成交及浏览概率等）的用户	PRODUCT_ATTRIBUTE
关键词定向	730	针对输入的关键词，系统选择出相关度（时间窗内，搜索行为等频次）高的用户	KEYWORD
店铺行为重定向	500	自定义当前店铺行为和时间窗下覆盖的人群	SHOP_BEHAVIOR
宝贝偏好重定向	501	针对选择的当前店铺中宝贝，系统挑选出更适合（时间窗内，浏览点击成交等行为概率）的人群	LIKE_MY_ITEM
渠道人群重定向	502	针对选择的渠道，系统挑选出更适合（时间窗内，浏览点击成交等行为概率）的人群	CHANNEL
粉丝分层重定向	600	针对选择的粉丝分层，系统挑选出更适合（时间窗内，对应的行为）的人群	FANS
店铺优质人群定向	32768	系统挑选出更优质（时间窗内，成交点击等效果指标优秀）的店铺行为人群	SHOP_INTELLIGENCE
宝贝优质人群定向	1048576	针对选择的宝贝，系统挑选出更优质（时间窗内，成交点击等效果指标优秀）的宝贝行为人群	ITEM_INTELLIGENCE
达摩盘平台精选定向	4194304	阿里运营通过达摩盘圈定的行业或商家定制人群	DSP_DMP
达摩盘定向	128	商家自定义的达摩盘人群	ADV_DMP

二、 新定向统一结构介绍

本着“降低客户使用及理解的成本，降低定向升级给客户带去的负担，提高定向给客户带去的便利”的原则，本期重构了整个定向及人群结构，以促进客户更好的理解定向体系和人群，未来的定向升级将变成数据的迭代，客户端无需进行结构调整，仅需要按照对应的新文档和当前结构获取新数据即可享受和web端完全一致的定向能力以及定向所带来的新优势。

1、概念解读

• 标签及选项

所有的数据均被结构化为两层，即一颗深度为1的树，根节点是标签，叶子节点是选项，一个标签下可包含多个选项，标签是对大类型数据的分类描述，选项是针对该类型的范围进行区隔，比如：性别、年龄，就是典型的标签，18岁~30岁，30岁~50岁，男，女，就是对应这些标签的选项。

• 定向

所有标签选项的背后，都是数据，而数据的生产和最终广告使用并投放的过程，需要算法策略的干预，不同类型的数据势必会有对应的算法模型进行优化，因此，我们把标签打包定义为了定向，而不同的算法模型就是根据其中的定向类型（targetType）进行识别，在数据构建及投放预估中影响算法模型，因此，定向是一个系统层面的打包概念，比如上述提到的性别、年龄，对应的定向就是人口属性，对应的算法就是基础自然流量属性模型。

• 人群

针对展示广告投放场景，每一个推广单元都可以选择一系列的人群进行投放，最终可以在人群上进行出价并获得参竞机会，因此，人群具备数据和营销的双重属性，包含出价、绑定在单元计划、数据等信息，所以人群是由定向加营销属性共同构成的实体。
?

2、结构解读

选项Option

// 选项结构
public class UpgradeOptionDTO {    
    // 选项id
    private Long id;

    // 选项名称
    private String optionName;

    // 选项值，数据标识
    private String optionValue;

    // 选项状态
    private Integer status;

    // 选项描述
    private String optionDesc;

    // 选项附属信息
    private Map<String, String> properties = new HashMap(5);
}

标签Label

// 标签定向结构
public class UpgradeTargetLabelDTO {
    // 标签id
    private Long labelId;

    // 定向id
    private Long targetId;

    // 定向类型
    private String targetType;

    // 标签名称
    private String labelName;

    // 标签描述
    private String labelDesc;

    // 标签状态
    private Integer status;

    // 标签值，数据标识
    private String labelValue;

    // 选项
    private List<UpgradeOptionDTO> options;
}

人群crowd

// 人群结构
public class UpgradeCrowdDTO {
    // 人群id
    private Long id;

    // 人群名称
    private String crowdName;

    // 人群描述
    private String crowdDesc;

    // 计划id
    private Long campaignId;

    // 单元id
    private Long adgroupId;

    // 交叉出价
    private List<MatrixPriceDTO> matrixPrice = new ArrayList<MatrixPriceDTO>();

    // 是否绑定人群
    private boolean bindCrowd = true;

    // 标签
    private UpgradeTargetLabelDTO targetLabel;

    // 人群状态
    private String status;
}

新人群查询结构

public class UpgradeCrowdQuery {
    //当前页要显示数据的起始位置
    private int offset = 0;

    //每页显示的记录条数
    private int pageSize = 50;
    
    //必填，单元id
    private Long adgroupId;
    
    //必填，计划id
    private Long campaignId;
    
    //人群id
    private Long crowdId;
    
    //定向类型
    private String targetType;
    
    //计划名称
    private String campaignName;
    
    //人群名称
    private String crowdName;
    
    //单元名称
    private String adgroupName;
    
    //人群状态
    private String status;
    
    //人群类型列表
    private List<String> targetTypes;

}

定向结构

public class UpgradeTargetDTO {

    //定向名称
    private String targetName;
    
    //定向描述
    private String targetDesc;
    
    //定向类型
    private String targetType;
}

三、 新定向统一接口介绍

统一结构带来了统一的接口，并且本次定向升级从模拟客户真实的使用场景出发，提供了从数据查询到人群创建、人群查询及更新删除的全链路接口，客户的整个使用过程可以抽象为：

• 查询数据

通过接口taobao.zuanshi.banner.upgrade.target.find可以获取当前客户有权限使用的定向列表，然后通过定向类型targetType可以构建出查询条件获取当前定向下可使用的标签选项数据信息，接口为taobao.zuanshi.banner.upgrade.target.label.find

• 平台工具

针对获取的数据，平台还提供了查询覆盖PV的接口taobao.zuanshi.banner.upgrade.target.predict.pv，以及查询覆盖UV的接口taobao.zuanshi.banner.upgrade.target.predict.uv，针对无从下手的客户，还提供了系统层面针对当前定向的推荐数据接口taobao.zuanshi.banner.upgrade.target.suggest.find

• 创建人群并绑定推广单元

通过查询数据获取的数据信息，可以自定义的选择当前推广单元需要的信息，裁剪成为人群结构中的标签数据，一般是根据名称删除一些不需要的option和label，并不需要关心返回结构中多余的其他属性，然后再根据当前投放场景，构造出出价和计划单元信息，而后调用taobao.zuanshi.banner.upgrade.crowd.add接口进行创建人群操作

• 分页查询单元下绑定的人群

创建完人群之后，可以通过taobao.zuanshi.banner.upgrade.crowd.page接口获取对应单元下已经绑定的人群列表

• 全量更新单元下绑定的人群

客户想要调整人群时，可以通过查询出来的人群进行调整，然后全量替换掉当前单元下的人群，接口为taobao.zuanshi.banner.upgrade.crowd.update

• 删除单元下绑定的人群

客户想要删除人群时，可以通过查询出来的人群，选择出想要删除的人群id，调用taobao.zuanshi.banner.upgrade.crowd.delete进行删除

1、新增人群及绑定推广单元

• 接口：

taobao.zuanshi.banner.upgrade.crowd.add

• 入参说明：

/**
 * 人群数据，通过查询标签获得的UpgradeTargetLabelDTO结构，再需求化的裁剪之后，构建出所需要的标签，进而组装所需要的单元信息adgroupId、计划信息campaignId以及人群名称crowdName、交叉出价matrixPrice等信息，构建出UpgradeCrowdDTO对象，进行人群绑定
 */
List<UpgradeCrowdDTO> crowds

• 出参说明：

/**
 * 返回结果，false-错误，true-正确
 */
success

/**
 * 返回结果
 */
message

• 示例：

新建DMP人群，并绑定推广单元，其中target_label是通过接口taobao.zuanshi.banner.upgrade.target.label.find查询后进行裁剪而来

[
  {
    "adgroup_id": 501118506,
    "campaign_id": 501118504,
    "crowd_desc": "卡卡的DESC",
    "crowd_name": "卡卡的测试人群",
    "matrix_price": [
      {
        "adzone_id": 61366002,
        "price": 100
      }
    ],
    "status": "1",
    "target_label": {
      "label_id": 115193,
      "label_name": "我创建的人群",
      "label_value": "{optionValue}",
      "options": [
        {
          "option_name": "测试人群21421",
          "option_value": "2614062"
        },
        {
          "option_name": "测试人群21421",
          "option_value": "2614062"
        },
        {
          "option_name": "测试人群21421",
          "option_value": "2614062"
        }
      ],
      "target_id": 137,
      "target_type": "ADV_DMP"
    }
  }
]

##### 2、全量更新人群及绑定推广单元

* 接口：

`taobao.zuanshi.banner.upgrade.crowd.update`

* 入参说明：

?```java
/**
 * 人群数据，通过查询人群接口获得当前adgroup下所有的定向，然后裁剪其中的crowd，挑选出需要变更的人群，构建出全量替换的人群对象
 */
List<UpgradeCrowdDTO> crowds

• 出参说明：

/**
 * 返回结果，false-错误，true-正确
 */
success

/**
 * 返回结果
 */
message

• 示例：

更新DMP人群，通过接口taobao.zuanshi.banner.upgrade.crowd.page获取人群信息，然后进行相应的业务调整之后，更新对应的人群

[
  {
    "adgroup_id": 501118506,
    "campaign_id": 501118504,
    "crowd_desc": "DESC",
    "crowd_name": "测试人群",
    "matrix_price": [
      {
        "adzone_id": 61366002,
        "price": 300
      }
    ],
    "status": "1",
    "target_label": {
      "label_id": 115193,
      "label_name": "我创建的人群",
      "label_value": "{optionValue}",
      "options": [
        {
          "option_name": "测试人群21421",
          "option_value": "2614062"
        }
      ],
      "target_id": 137,
      "target_type": "ADV_DMP"
    }
  }
]

3、删除定向人群

• 接口：taobao.zuanshi.banner.upgrade.crowd.delete

• 入参说明：

java /** * 人群数据，通过查询人群接口获取待删除的定向人群数据，剪裁crowd，通过保留campaignId,adgroupId,id来指定待删除的人群。 */ List<UpgradeCrowdDTO> crowds

• 出参说明：

java /** * 返回结果，false-错误，true-正确 */ success

• 示例：

通过taobao.zuanshi.banner.upgrade.crowd.page获取人群信息，通过crowd中的id，campainId，adgroupId进行删除

json [ { "campaign_id": 501118504, "adgroup_id": 501118506, "id": 31231123 } ]

#### 4、查询某个定向类型下的标签以及标签选项

• 接口：taobao.zuanshi.banner.upgrade.target.label.find

• 入参说明：

```java
/**
* 标签查询参数
/
public class UpgradeTargetLabelQuery targetLabelQuery {
/
* 当前页要显示数据的起始位置，默认0
*/
private int optionOffset = 0;

/**
   * 每页显示的记录条数，默认100
   */
  private int optionPageSize = 100;

  /**
   * 必填，定向类型
   */
  private String targetType;

  /**
  * 选项名称，用于根据选项名称进行搜索场景
  */
  private String optionName;

  /**
  * 计划结算类型，cpc/cpm
  */
  private String campaignType;

}
```

• 出参说明：

java /** * 返回结果，false-错误，true-正确 */ success /** * 返回结果 */ List<UpgradeTargetLabelDTO> labelList

• 示例1：

通过taobao.zuanshi.banner.upgrade.target.find获取有权限的定向信息，并查询访客定向的标签入参如下。

json { "target_type":"SHOP_VISITOR" }

#### 5、查询某些标签的pv预估

• 接口：taobao.zuanshi.banner.upgrade.target.predict.pv

• 入参说明：

java /** * 标签数据，通过查询标签获得的UpgradeTargetLabelDTO结构，经过剪裁后保留选择的label和option进行pv预估。支持多个类型的定向同时预估。 */ List<UpgradeTargetLabelDTO> targetLabels

• 出参说明：

```java
/**
* 返回结果，false-错误，true-正确
*/
success

/**
* 返回结果
*/
result
```

• 示例：

预估DMP人群全定的pv数量

json [ { "label_id": 115193, "label_name": "我创建的人群", "label_value": "{optionValue}", "options": [ { "option_name": "测试人群21421", "option_value": "2614062" }, { "option_name": "测试人群21421", "option_value": "2614062" }, { "option_name": "测试人群21421", "option_value": "2614062" } ], "target_id": 137, "target_type": "ADV_DMP" } ]

##### 6、查询某些标签的uv预估

• 接口：taobao.zuanshi.banner.upgrade.target.predict.uv

• 入参说明：

java /** * 标签数据，通过查询标签获得的UpgradeTargetLabelDTO结构，经过剪裁后保留选择的label和option进行pv预估。支持多个类型的定向同时预估。 */ List<UpgradeTargetLabelDTO> targetLabels

• 出参说明：

```java
/**
* 返回结果，false-错误，true-正确
*/
success

/**
* 返回结果
*/
result
```

• 示例：

预估DMP人群全定的uv数量

json [ { "label_id": 115193, "label_name": "我创建的人群", "label_value": "{optionValue}", "options": [ { "option_name": "测试人群21421", "option_value": "2614062" }, { "option_name": "测试人群21421", "option_value": "2614062" }, { "option_name": "测试人群21421", "option_value": "2614062" } ], "target_id": 137, "target_type": "ADV_DMP" } ]

7. 查询已绑定的人群

• 接口：

taobao.zuanshi.banner.upgrade.crowd.page

• 入参说明：

/**
* 人群查询结构，通过接口分页获取指定计划与单元下的定向人群数据，由 UpgradeCrowdQuery 中的 offset控制 起始页， pageSize控制页面记录条数
*/
UpgradeCrowdQuery crowdQuery

• 出参说明：

/**
 * 返回结果，false-错误，true-正确
 */
Boolean success

/**
* 返回结果对象
*/
List<UpgradeCrowdDTO> crowd_list

/**
* 定向总个数
*/
Integer total_count;

*示例：

需要获取指定计划与单元下的定向人群数据，adgroup_id 与 campaign_id 必填

{
  "adgroup_id": 501118506,
  "campaign_id": 501118504
}

8. 查询有权限的定向列表

• 接口：

taobao.zuanshi.banner.upgrade.target.find

• 入参说明：

/**
* 计划结算类型cpc/cpm 
**/
String campaignType

• 出参说明：

/**
 * 返回结果，false-错误，true-正确
 */
Boolean success

/**
* 返回结果对象
*/
List<UpgradeCrowdDTO> target_list

*示例：

无

9. 定向推荐查询

• 接口：

taobao.zuanshi.banner.upgrade.target.suggest.find

• 入参说明：

/**
* 定向类型
*/
String targetType

/**
* 计划结算类型：cpm/cpc
*/
String campaignType

• 出参说明：

/**
 * 返回结果，false-错误，true-正确
 */
Boolean success

/**
* 返回结果对象
*/
List<UpgradeTargetLabelDTO> label_list

*示例：

{
  "campaign_type": "cpm",
  "target_type": "ALL"
}

FAQ

关于此文档暂时还没有FAQ