feat(audiencepackage): 定向包相关接口能力升级拓展更新支持推广场景

marketing-api/OCEANENGINE.md

@@ -440,7 +440,9 @@
     - 查询深度优化方式 [ DeepbidRead(clt *core.SDKClient, accessToken string, req *adconvert.DeepbidReadRequest) ([]enum.DeepBidType, error) ]
     - 修改转化监测链接 [ TrackURLUpdateStatus(clt *core.SDKClient, accessToken string, req *adconvert.TrackURLUpdateRequest) error ]
   - 定向包管理 (audiencepackage)
-    - 获取定向包 [ Get(clt *core.SDKClient, accessToken string, req *audiencepackage.GetRequest) (*audiencepackage.GetResponseData, error) ]
+    - 定向包查询关联项目信息 [ v3.BindInfoGet(ctx context.Context, clt *core.SDKClient, accessToken string, req *v3.BindInfoGetRequest) (*v3.BindInfoGetResult, error) ]
+    - 获取定向包 [ v3.Get(clt *core.SDKClient, accessToken string, req *v3.GetRequest) (*v3.GetResult, error) ]
+    - 获取定向包(旧) [ Get(clt *core.SDKClient, accessToken string, req *audiencepackage.GetRequest) (*audiencepackage.GetResponseData, error) ]
     - 创建定向包 [ Create(clt *core.SDKClient, accessToken string, req *audiencepackage.CreateRequest) (uint64, error) ]
     - 更新定向包 [ Update(clt *core.SDKClient, accessToken string, req *audiencepackage.UpdateRequest) (uint64, error) ]
     - 删除定向包 [ Delete(clt *core.SDKClient, accessToken string, req *audiencepackage.DeleteRequest) (uint64, error) ]

marketing-api/api/audiencepackage/v3/bindinfo_get.go

@@ -0,0 +1,19 @@
+package v3
+
+import (
+	"context"
+
+	"github.com/bububa/oceanengine/marketing-api/core"
+	v3 "github.com/bububa/oceanengine/marketing-api/model/audiencepackage/v3"
+)
+
+// BindInfoGet 定向包查询关联项目信息
+// 定向包查询关联项目信息
+// 可通过【获取定向包】接口获取定向包ID，根据定向包ID查询该定向包关联了哪些项目
+func BindInfoGet(ctx context.Context, clt *core.SDKClient, accessToken string, req *v3.BindInfoGetRequest) (*v3.BindInfoGetResult, error) {
+	var resp v3.BindInfoGetResponse
+	if err := clt.GetAPI(ctx, "v3.0/audience_package_bindinfo/get/", req, &resp, accessToken); err != nil {
+		return nil, err
+	}
+	return resp.Data, nil
+}

marketing-api/api/audiencepackage/v3/doc.go

@@ -0,0 +1,2 @@
+// Package v3 定向包相关V3
+package v3

marketing-api/api/audiencepackage/v3/get.go

@@ -0,0 +1,21 @@
+package v3
+
+import (
+	"context"
+
+	"github.com/bububa/oceanengine/marketing-api/core"
+	v3 "github.com/bububa/oceanengine/marketing-api/model/audiencepackage/v3"
+)
+
+// Get 获取定向包
+// 落地页：可用于推广目的为销售线索收集或推广目的为应用推广且下载方式为落地页的计划
+// 应用推广（Android）：可用于推广目的为应用推广且下载方式为Android下载链接的计划
+// 应用推广（iOS）：可用于推广目的为应用推广且下载方式为iOS下载链接的计划
+// 其余类型：可应用于推广目的为该类型名称的计划
+func Get(ctx context.Context, clt *core.SDKClient, accessToken string, req *v3.GetRequest) (*v3.GetResult, error) {
+	var resp v3.GetResponse
+	if err := clt.GetAPI(ctx, "v3.0/audience_package/get/", req, &resp, accessToken); err != nil {
+		return nil, err
+	}
+	return resp.Data, nil
+}

marketing-api/enum/audience_package_filter_event.go

@@ -0,0 +1,15 @@
+package enum
+
+// AudiencePackageFiltetEvent 自定义过滤事件
+type AudiencePackageFiltetEvent string
+
+const (
+	// AudiencePackageFiltetEvent_AD_CONVERT_EXTERNAL_ACTION 优化目标
+	AudiencePackageFiltetEvent_AD_CONVERT_EXTERNAL_ACTION AudiencePackageFiltetEvent = "AD_CONVERT_EXTERNAL_ACTION"
+	// AudiencePackageFiltetEvent_AD_CONVERT_TYPE_ACTIVE 激活
+	AudiencePackageFiltetEvent_AD_CONVERT_TYPE_ACTIVE AudiencePackageFiltetEvent = "AD_CONVERT_TYPE_ACTIVE"
+	// AudiencePackageFiltetEvent_AD_CONVERT_TYPE_ACTIVE_REGISTER 注册
+	AudiencePackageFiltetEvent_AD_CONVERT_TYPE_ACTIVE_REGISTER AudiencePackageFiltetEvent = "AD_CONVERT_TYPE_ACTIVE_REGISTER"
+	// AudiencePackageFiltetEvent_AD_CONVERT_TYPE_PAY 付费
+	AudiencePackageFiltetEvent_AD_CONVERT_TYPE_PAY AudiencePackageFiltetEvent = "AD_CONVERT_TYPE_PAY"
+)

marketing-api/enum/local/converted_time_duration.go → marketing-api/enum/converted_time_duration.go

@@ -1,4 +1,4 @@
-package local
+package enum
 
 // ConvertedTimeDuration 过滤已转化投放时间
 type ConvertedTimeDuration string

marketing-api/enum/local/hide_if_converted.go → marketing-api/enum/hide_if_converted.go

@@ -1,11 +1,15 @@
-package local
+package enum
 
 // HideIfConverted 过滤已转化的维度，可以避免该广告再次投放给已转化过的用户，不传默认不过滤
 type HideIfConverted string
 
 const (
 	// HideIfConverted_NOT_EXCLUDE 不过滤
 	HideIfConverted_NOT_EXCLUDE HideIfConverted = "NOT_EXCLUDE"
+	// HideIfConverted_APP 应用
+	HideIfConverted_APP HideIfConverted = "APP"
+	// HideIfConverted_ORGANIZATION 组织（仅加白广告主可用）
+	HideIfConverted_ORGANIZATION HideIfConverted = "ORGANIZATION"
 	// HideIfConverted_ADVERTISER 广告主账户
 	HideIfConverted_ADVERTISER HideIfConverted = "ADVERTISER"
 	// HideIfConverted_CC 组织账户

marketing-api/enum/hide_if_exists.go

@@ -0,0 +1,55 @@
+package enum
+
+import "strconv"
+
+// HideIfExists 已安装用户
+// 0表示不限，1表示过滤，2表示定向；过滤表示投放时不给安装客户展示广告，支持应用推广；定向表示投放时给安装客户展示广告；投放时优先获取直达链接，无直达链接时使用应用包名进行投放；如果无直达链接或应用包名，定向安装选项实际不生效；定向仅对Android链接生效。
+type HideIfExists string
+
+const (
+	// HideIfExists_UNLIMITED 不限（默认值）
+	HideIfExists_UNLIMITED HideIfExists = "UNLIMITED"
+	// HideIfExists_FILTER 过滤，仅安卓应用推广时支持，其他情况传入不生效
+	HideIfExists_FILTER HideIfExists = "FILTER"
+	// HideIfExists_TARGETING 定向
+	HideIfExists_TARGETING HideIfExists = "TARGET"
+)
+
+// UnmarshalJSON implement json Unmarshal interface
+func (he *HideIfExists) UnmarshalJSON(b []byte) (err error) {
+	if b[0] == '"' && b[len(b)-1] == '"' {
+		b = b[1 : len(b)-1]
+	}
+	var ret int
+	str := string(b)
+	switch str {
+	case "UNLIMITED":
+		ret = 0
+	case "FILTER":
+		ret = 1
+	case "TARGETING":
+		ret = 2
+	default:
+		ret, _ = strconv.Atoi(str)
+	}
+	*he = HideIfExists(ret)
+	return
+}
+
+func (he HideIfExists) Value() int {
+	switch he {
+	case HideIfExists_FILTER:
+		return 1
+	case HideIfExists_TARGETING:
+		return 2
+	default:
+		return 0
+	}
+}
+
+func (he HideIfExists) String() string {
+	if he == "" {
+		return string(HideIfExists_UNLIMITED)
+	}
+	return string(he)
+}

marketing-api/enum/onoff.go

@@ -0,0 +1,10 @@
+package enum
+
+type OnOff string
+
+const (
+	// ON 开启
+	ON OnOff = "ON"
+	// OFF 关闭
+	OFF OnOff = "OFF"
+)

marketing-api/model/ad/ad.go

@@ -94,7 +94,7 @@ type Ad struct {
 	// FeedDeliverySearch 搜索快投关键词，HAS_OPEN:启用，DISABLE:不启用
 	FeedDeliverySearch string `json:"feed_delivery_search,omitempty"`
 	// IntelligentFlowSwitch 智能流量开关，ON:开启，OFF:关闭
-	IntelligentFlowSwitch string `json:"intelligent_flow_switch,omitempty"`
+	IntelligentFlowSwitch enum.OnOff `json:"intelligent_flow_switch,omitempty"`
 	// OpenUrl 直达链接(点击唤起APP)
 	OpenUrl string `json:"open_url,omitempty"`
 	// AdvancedCreativeType 附加创意类型; 允许值: ATTACHED_CREATIVE_GAME_PACKAGE游戏礼包码,ATTACHED_CREATIVE_GAME_FORM游戏表单收集,ATTACHED_CREATIVE_GAME_SUBSCRIBE游戏预约,ATTACHED_CREATIVE_NONE无推广目的为应用推广类型、下载方式选择下载链接且下载链接为安卓应用下载时才可以设置
@@ -178,11 +178,11 @@ type Ad struct {
 	// AudiencePackageID 定向包ID
 	AudiencePackageID uint64 `json:"audience_package_id,omitempty"`
 	// HideIfExists 过滤已安装，当推广目标为安卓应用下载时可填，0表示不限，1表示过滤，2表示定向。默认为不限;默认值:0; 取值: 0, 1, 2。建议促进app活跃度客户使用定向安装功能。选择定向安装时，向已安装客户展示广告；投放时优先获取直达链接，无直达链接时使用应用包名进行投放；如果无直达链接或应用包名，定向安装选项实际不生效；仅对Android链接生效。
-	HideIfExists int `json:"hide_if_exists,omitempty"`
+	HideIfExists enum.HideIfExists `json:"hide_if_exists,omitempty"`
 	// HideIfConverted 过滤已转化用户
-	HideIfConverted string `json:"hide_if_converted,omitempty"`
+	HideIfConverted enum.HideIfConverted `json:"hide_if_converted,omitempty"`
 	// ConvertedTimeDuration 过滤时间范围
-	ConvertedTimeDuration string `json:"converted_time_duration,omitempty"`
+	ConvertedTimeDuration enum.ConvertedTimeDuration `json:"converted_time_duration,omitempty"`
 	// DpaLbs 地域匹配-LBS;开启时，根据用户的地理位置信息，给用户投放位于其附近的产品 ;取值：0，1（0表示不启用，1表示启用）
 	DpaLbs *int `json:"dpa_lbs,omitempty"`
 	// DpaCity 地域匹配-商品所在城市;开启时，仅将商品投放给位于该商品设置的可投城市的用户 ;取值：0，1（0表示不启用，1表示启用）
@@ -246,7 +246,7 @@ type Ad struct {
 	// LauhchTargetType 投放类型，LIVE_CONVERT：直播间转化、APP：应用下载、EXTERNAL：线索收集
 	LaunchTargetType string `json:"launch_target_type,omitempty"`
 	// AutoUpdateKeyword 是否开启自动加词，ON 开启、OFF 关闭
-	AutoUpdateKeyword string `json:"auto_update_keyword,omitempty"`
+	AutoUpdateKeyword enum.OnOff `json:"auto_update_keyword,omitempty"`
 	// LandingPageStayTime 店铺停留时长，单位为毫秒
 	LandingPageStayTime int64 `json:"landing_page_stay_time,omitempty"`
 	// TargetCvr 目标转化率
@@ -322,7 +322,7 @@ type Audience struct {
 	// FilterOwnAwemeFans （抖音号推广特有）过滤自己的粉丝; 取值：0表示不过滤，1表示过滤
 	FilterOwnAwemeFans int `json:"filter_own_aweme_fans,omitempty"`
 	// SuperiorPopularityType 媒体定向;
-	SuperiorPopularityType string `json:"superior_popularity_type,omitempty"`
+	SuperiorPopularityType enum.SuperiorPopularityType `json:"superior_popularity_type,omitempty"`
 	// FlowPackage 定向逻辑
 	FlowPackage []uint64 `json:"flow_package,omitempty"`
 	// ExcludeFlowPackage 排除定向逻辑
@@ -352,7 +352,7 @@ type Audience struct {
 	// AutoExtendTarget 可放开定向。当auto_extend_enabled=1 时选填。详见：【附录-可开放定向】。缺省为全不选。
 	AutoExtendTarget []string `json:"auto_extend_targets,omitempty"`
 	// DpaRtaSwitch RTA重定向选项，值：ON:开启，OFF：关闭
-	DpaRtaSwitch string `json:"dpa_rta_switch,omitempty"`
+	DpaRtaSwitch enum.OnOff `json:"dpa_rta_switch,omitempty"`
 	// DpaRtaRecommendType RTA推荐逻辑，ONLY:仅RTA推荐商品，MORE：基于RTA推荐更多商品
 	DpaRtaRecommendType string `json:"dpa_rta_recommend_type,omitempty"`
 }
@@ -364,21 +364,27 @@ func (a Ad) Version() model.AdVersion {
 func (a Ad) GetID() uint64 {
 	return a.ID
 }
+
 func (a Ad) GetName() string {
 	return a.Name
 }
+
 func (a Ad) GetCampaignID() uint64 {
 	return a.CampaignID
 }
+
 func (a Ad) GetAdvertiserID() uint64 {
 	return a.AdvertiserID
 }
+
 func (a Ad) GetOptStatus() enum.AdOptStatus {
 	return a.OptStatus
 }
+
 func (a Ad) GetBudget() float64 {
 	return a.Budget
 }
+
 func (a Ad) GetCpaBid() float64 {
 	return a.CpaBid
 }

marketing-api/model/ad/create.go

@@ -113,7 +113,7 @@ type CreateRequest struct {
 	// FeedDeliverySearch 搜索快投关键词，HAS_OPEN:启用，DISABLE:不启用
 	FeedDeliverySearch string `json:"feed_delivery_search,omitempty"`
 	// IntelligentFlowSwitch 智能流量开关，ON:开启，OFF:关闭
-	IntelligentFlowSwitch string `json:"intelligent_flow_switch,omitempty"`
+	IntelligentFlowSwitch enum.OnOff `json:"intelligent_flow_switch,omitempty"`
 	// AudiencePackageID 定向包ID
 	AudiencePackageID uint64 `json:"audience_package_id,omitempty"`
 	// District 地域;取值: "CITY"省市, "COUNTY"区县, "BUSINESS_DISTRICT"商圈,"NONE"不限，省市传法："city": [12],"district": "CITY",区县的传法："city": [130102],"district": "COUNTY";暂不支持"海外"
@@ -167,7 +167,7 @@ type CreateRequest struct {
 	// FilterOwnAwemeFans （抖音号推广特有）过滤自己的粉丝; 取值：0表示不过滤，1表示过滤
 	FilterOwnAwemeFans *int `json:"filter_own_aweme_fans,omitempty"`
 	// SuperiorPopularityType 媒体定向;
-	SuperiorPopularityType string `json:"superior_popularity_type,omitempty"`
+	SuperiorPopularityType enum.SuperiorPopularityType `json:"superior_popularity_type,omitempty"`
 	// FlowPackage 定向逻辑
 	FlowPackage []uint64 `json:"flow_package,omitempty"`
 	// ExcludeFlowPackage 排除定向逻辑
@@ -187,9 +187,9 @@ type CreateRequest struct {
 	// HideIfExists 过滤已安装，当推广目标为安卓应用下载时可填，0表示不限，1表示过滤，2表示定向。默认为不限;默认值:0; 取值: 0, 1, 2。建议促进app活跃度客户使用定向安装功能。选择定向安装时，向已安装客户展示广告；投放时优先获取直达链接，无直达链接时使用应用包名进行投放；如果无直达链接或应用包名，定向安装选项实际不生效；仅对Android链接生效。
 	HideIfExists int `json:"hide_if_exists,omitempty"`
 	// HideIfConverted 过滤已转化用户
-	HideIfConverted string `json:"hide_if_converted,omitempty"`
+	HideIfConverted enum.HideIfConverted `json:"hide_if_converted,omitempty"`
 	// ConvertedTimeDuration 过滤时间范围
-	ConvertedTimeDuration string `json:"converted_time_duration,omitempty"`
+	ConvertedTimeDuration enum.ConvertedTimeDuration `json:"converted_time_duration,omitempty"`
 	// ActivateType 新用户(新用户使用头条的时间)
 	ActivateType []enum.ActivateType `json:"activate_type,omitempty"`
 	// ArticleCategory 文章分类
@@ -217,7 +217,7 @@ type CreateRequest struct {
 	// DpaRecommendType dpa商品重定向推荐类型，dpa_local_audience为1时有值;取值：1（基于重定向推荐更多商品(根据重定向商品和行业特点，推荐更多相关商品投放，包含重定向商品），2仅重定向商品（仅根据重定向人群内定义的重定向行为商品进行投放）
 	DpaRecommendType int `json:"dpa_recommend_type,omitempty"`
 	// DpaRtaSwitch RTA重定向选项，值：ON:开启，OFF：关闭
-	DpaRtaSwitch string `json:"dpa_rta_switch,omitempty"`
+	DpaRtaSwitch enum.OnOff `json:"dpa_rta_switch,omitempty"`
 	// DpaRtaRecommendType RTA推荐逻辑，ONLY:仅RTA推荐商品，MORE：基于RTA推荐更多商品
 	DpaRtaRecommendType string `json:"dpa_rta_recommend_type,omitempty"`
 	// SmartBidType 投放场景(出价方式)，详见【附录-自动出价类型】;允许值: 常规投放"SMART_BID_CUSTOM", 放量投放"SMART_BID_CONSERVATIVE"; 概念解释：常规投放：控制成本，尽量消耗完预算；放量投放：接受成本上浮，尽量消耗更多预算
@@ -276,7 +276,7 @@ type CreateRequest struct {
 	// 客户端上传是指由客户端直接上报给监测平台的服务器, 只有白名单用户才可使用CLIENT_SEND(客户端上传), 如果需要开通请找对接的销售、运营
 	TrackURLSendType string `json:"track_url_send_type,omitempty"`
 	// AutoUpdateKeyword 是否开启自动加词，ON 开启、OFF 关闭
-	AutoUpdateKeyword string `json:"auto_update_keyword,omitempty"`
+	AutoUpdateKeyword enum.OnOff `json:"auto_update_keyword,omitempty"`
 }
 
 // Encode implement PostRequest interface

marketing-api/model/ad/update.go

@@ -57,7 +57,7 @@ type UpdateRequest struct {
 	// FeedDeliverySearch 搜索快投关键词，HAS_OPEN:启用，DISABLE:不启用
 	FeedDeliverySearch string `json:"feed_delivery_search,omitempty"`
 	// IntelligentFlowSwitch 智能流量开关，ON:开启，OFF:关闭
-	IntelligentFlowSwitch string `json:"intelligent_flow_switch,omitempty"`
+	IntelligentFlowSwitch enum.OnOff `json:"intelligent_flow_switch,omitempty"`
 	// AudiencePackageID 定向包ID
 	AudiencePackageID uint64 `json:"audience_package_id,omitempty"`
 	// District 地域;取值: "CITY"省市, "COUNTY"区县, "BUSINESS_DISTRICT"商圈,"NONE"不限，省市传法："city": [12],"district": "CITY",区县的传法："city": [130102],"district": "COUNTY";暂不支持"海外"
@@ -111,7 +111,7 @@ type UpdateRequest struct {
 	// FilterOwnAwemeFans （抖音号推广特有）过滤自己的粉丝; 取值：0表示不过滤，1表示过滤
 	FilterOwnAwemeFans *int `json:"filter_own_aweme_fans,omitempty"`
 	// SuperiorPopularityType 媒体定向;
-	SuperiorPopularityType string `json:"superior_popularity_type,omitempty"`
+	SuperiorPopularityType enum.SuperiorPopularityType `json:"superior_popularity_type,omitempty"`
 	// FlowPackage 定向逻辑
 	FlowPackage *[]uint64 `json:"flow_package,omitempty"`
 	// ExcludeFlowPackage 排除定向逻辑
@@ -131,9 +131,9 @@ type UpdateRequest struct {
 	// HideIfExists 过滤已安装，当推广目标为安卓应用下载时可填，0表示不限，1表示过滤，2表示定向。默认为不限;默认值:0; 取值: 0, 1, 2。建议促进app活跃度客户使用定向安装功能。选择定向安装时，向已安装客户展示广告；投放时优先获取直达链接，无直达链接时使用应用包名进行投放；如果无直达链接或应用包名，定向安装选项实际不生效；仅对Android链接生效。
 	HideIfExists *int `json:"hide_if_exists,omitempty"`
 	// HideIfConverted 过滤已转化用户
-	HideIfConverted string `json:"hide_if_converted,omitempty"`
+	HideIfConverted enum.HideIfConverted `json:"hide_if_converted,omitempty"`
 	// ConvertedTimeDuration 过滤时间范围
-	ConvertedTimeDuration string `json:"converted_time_duration,omitempty"`
+	ConvertedTimeDuration enum.ConvertedTimeDuration `json:"converted_time_duration,omitempty"`
 	// ActivateType 新用户(新用户使用头条的时间)
 	ActivateType *[]enum.ActivateType `json:"activate_type,omitempty"`
 	// ArticleCategory 文章分类
@@ -197,7 +197,7 @@ type UpdateRequest struct {
 	// VideoPlayTrackURL 视频播放（监测链接），只允许传入1个，投放范围为穿山甲时暂不支持设置此链接
 	VideoPlayTrackURL *[]string `json:"video_play_track_url,omitempty"`
 	// AutoUpdateKeyword 否开启自动加词，允许值：ON（开启）、OFF（关闭）
-	AutoUpdateKeyword string `json:"auto_update_keyword,omitempty"`
+	AutoUpdateKeyword enum.OnOff `json:"auto_update_keyword,omitempty"`
 }
 
 // Encode implement PostRequest interface

marketing-api/model/advertiser/account_fund_get.go

@@ -21,7 +21,7 @@ type AccountFundGetRequest struct {
 	// GrantTypeSplit 是否拆分赠款类型，允许值：
 	// ON 开启
 	// OFF 关闭（默认）
-	GrantTypeSplit string `json:"grant_type_split,omitempty"`
+	GrantTypeSplit enum.OnOff `json:"grant_type_split,omitempty"`
 }
 
 // Encode implement GetRequest interface
@@ -30,7 +30,7 @@ func (r AccountFundGetRequest) Encode() string {
 	values.Set("account_ids", string(util.JSONMarshal(r.AccountIDs)))
 	values.Set("account_type", string(r.AccountType))
 	if r.GrantTypeSplit != "" {
-		values.Set("grant_type_split", r.GrantTypeSplit)
+		values.Set("grant_type_split", string(r.GrantTypeSplit))
 	}
 	ret := values.Encode()
 	util.PutUrlValues(values)

marketing-api/model/advertiser/fund_get.go

@@ -3,6 +3,7 @@ package advertiser
 import (
 	"strconv"
 
+	"github.com/bububa/oceanengine/marketing-api/enum"
 	"github.com/bububa/oceanengine/marketing-api/model"
 	"github.com/bububa/oceanengine/marketing-api/util"
 )
@@ -13,15 +14,15 @@ type FundGetRequest struct {
 	AdvertiserID uint64 `json:"advertiser_id,omitempty"`
 	// GrantTypeSplit 是否拆分赠款类型，允许值：
 	// 开启 ON ，关闭 OFF（默认）
-	GrantTypeSplit string `json:"grant_type_split,omitempty"`
+	GrantTypeSplit enum.OnOff `json:"grant_type_split,omitempty"`
 }
 
 // Encode implement GetRequest interface
 func (r FundGetRequest) Encode() string {
 	values := util.GetUrlValues()
 	values.Set("advertiser_id", strconv.FormatUint(r.AdvertiserID, 10))
 	if r.GrantTypeSplit != "" {
-		values.Set("grant_type_split", r.GrantTypeSplit)
+		values.Set("grant_type_split", string(r.GrantTypeSplit))
 	}
 	ret := values.Encode()
 	util.PutUrlValues(values)