接口文档SDK业务专题开发者工具

朋友圈信息流 – 收集销售线索

                <?php

require_once __DIR__ . '/../../vendor/autoload.php'; // change path as needed
use TencentAds\TencentAds;
use TencentAds\Exception\TencentAdsResponseException;
use TencentAds\Exception\TencentAdsSDKException;

/*****
 * 本文件提供了一个创建一个朋友圈线索收集广告的示例
 */
class AddLeadsAds
{
    public static $tads;
    public static $ACCESS_TOKEN           = 'YOUR ACCESS TOKEN';
    public static $ACCOUNT_ID             = 'YOUR ACCOUNT ID';
    public static $ADCREATIVE_TEMPLATE_ID = 450; // 朋友圈单图文
    public static $IMAGE_PATH             = 'YOUR AD IMAGE PATH'; // 图片文件路径,450规格要求:800x450, <300K, png/jpg
    public static $IMAGE_PROFILE_PATH     = 'YOUR AD IMAGE PATH'; // Profile图片文件路径,200x200, <300K, png/jpg
    public static $AD_TITLE               = 'YOUR AD TEXT'; // 广告标题,450规格要求:字数:1~10
    public static $AD_DESCRIPTION         = 'YOUR AD DESCRIPTION'; // 广告文案,450规格要求:字数:1~30
    public static $AD_URL                 = 'YOUR AD PAGE URL'; // H5外链地址

    public function init()
    {
        $tads = TencentAds::init([
            'access_token' => static::$ACCESS_TOKEN,
            'is_debug'     => true,
        ]);
        $tads->useSandbox(); // 默认访问沙箱环境,如访问正式环境,请切换为$tads->useProduction()
        static::$tads = $tads;

        return $tads;
    }

    public function main()
    {
        try {
            /* @var TencentAds $tads */
            $tads = static::$tads;

            // 第一步,创建推广计划
            $campaignType = 'CAMPAIGN_TYPE_NORMAL'; // 普通展示广告
            $promotedObjectType = 'PROMOTED_OBJECT_TYPE_LEAD_AD'; // 线索收集
            $campaignId = $this->AddCampaign($tads, $campaignType, $promotedObjectType);
            // echo 'Campaign ID: ' . $campaignId . PHP_EOL;

            // 第二步,创建广告组,不允许使用定向包,因此在广告组里创建定向
            $siteSet = ['SITE_SET_MOMENTS']; // 投放微信流量
            $adgroupId = $this->AddAdgroup($tads, $campaignId, $promotedObjectType, $siteSet);
            // echo 'Adgroup ID: ' . $adgroupId . PHP_EOL;

            // 第三步,上传素材
            $imageId = $this->AddImage($tads, static::$IMAGE_PATH);
            // echo 'Image ID: ' . implode(', ', $imageIdList) . PHP_EOL;
            $imageIdLeads = $this->AddImage($tads, static::$IMAGE_PROFILE_PATH);
            // echo 'Image ID: ' . $imageIdLeads . PHP_EOL;
            $profileId = $this->AddProfile($tads, $promotedObjectType, $imageIdLeads);
            // echo 'Profile ID: ' . $profileId . PHP_EOL;

            // 第四步,创建创意
            $adcreativeId = $this->AddAdcreative($tads, static::$ADCREATIVE_TEMPLATE_ID, $campaignId,
                $promotedObjectType, $siteSet, $imageId, static::$AD_TITLE, static::$AD_DESCRIPTION,
                static::$AD_URL, $profileId);
            // echo 'Adcreative ID: ' . $adcreativeId . PHP_EOL;

            // 第五步,创建广告
            $adId = $this->AddAd($tads, $adgroupId, $adcreativeId);

            // echo 'Ad ID: ' . $adId . PHP_EOL;

            return $adId;
        } catch (TencentAdsResponseException $e) {
            // When Api returns an error
            echo 'Tencent ads returned an error: ' . $e->getMessage() . PHP_EOL;
            throw $e;
        } catch (TencentAdsSDKException $e) {
            // When validation fails or other local issues
            echo 'Tencent ads SDK returned an error: ' . $e->getMessage() . PHP_EOL;
            throw $e;
        } catch (Exception $e) {
            echo 'Other exception: ' . $e->getMessage() . PHP_EOL;
            throw $e;
        }
    }

    // 创建朋友圈推广计划
    protected function AddCampaign(TencentAds $tads, $campaignType, $promotedObjectType)
    {
        $campaignName = 'SDK sample campaign ' . uniqid();
        $campaignDailyBudget = 0;  // 不限日预算

        $campaign = $tads->campaigns()
                         ->add([
                             'account_id'           => static::$ACCOUNT_ID,
                             'campaign_name'        => $campaignName,
                             'campaign_type'        => $campaignType,
                             'promoted_object_type' => $promotedObjectType,
                             'daily_budget'         => $campaignDailyBudget,
                         ]);
        $campaignId = $campaign->getCampaignId();

        return $campaignId;
    }

    // 创建广告组
    protected function AddAdgroup(
        TencentAds $tads,
        $campaignId,
        $promotedObjectType,
        $siteSet
    ) {
        $adgroupName = 'SDK sample adgroup ' . uniqid();
        $beginDate = date('Y-m-d', strtotime('+1 day')); // 开始投放日期
        $endDate = date('Y-m-d', strtotime('+10 day')); // 结束投放日期
        $billingEvent = 'BILLINGEVENT_IMPRESSION'; // CPM
        $bidAmount = 5000; // 50元(单位为分)
        $optimizationGoal = 'OPTIMIZATIONGOAL_IMPRESSION'; // 优化目标展示
        $timeSeries = str_repeat('1', 48 * 7); // 全天投放
        $adgroupDailyBudget = 1000000; // 日预算10000元(单位为分)

        $targeting = [
            'age'          => [
                [ // 年龄定向,23~45岁
                  'min' => 23,
                  'max' => 45,
                ],
            ],
            'gender'       => ['MALE'], // 性别定向,男性
            'geo_location' => [ // 地域定向
                                'location_types' => ['LIVE_IN'],
                                'regions'        => ['110000'], // 北京
            ],
        ];

        $adgroup = $tads->adgroups()
                        ->add([
                            'account_id'           => static::$ACCOUNT_ID,
                            'campaign_id'          => $campaignId,
                            'adgroup_name'         => $adgroupName,
                            'promoted_object_type' => $promotedObjectType,
                            'begin_date'           => $beginDate,
                            'end_date'             => $endDate,
                            'billing_event'        => $billingEvent,
                            'bid_amount'           => $bidAmount,
                            'optimization_goal'    => $optimizationGoal,
                            'time_series'          => $timeSeries,
                            'site_set'             => $siteSet,
                            'daily_budget'         => $adgroupDailyBudget,
                            'targeting'            => $targeting,
                        ]);
        $adgroupId = $adgroup->getAdgroupId();

        return $adgroupId;
    }

    // 上传素材
    protected function AddImage(TencentAds $tads, $imageFile)
    {
        $imageSignature = md5_file($imageFile);
        $uploadType = 'UPLOAD_TYPE_FILE';
        $image = $tads->images()
                      ->add([
                          'account_id'  => static::$ACCOUNT_ID,
                          'upload_type' => $uploadType,
                          'file'        => $imageFile,
                          'signature'   => $imageSignature,
                      ]);
        $imageId = $image->getImageId();

        return $imageId;
    }

    // 创建微信原生页
    protected function AddWechatPage(TencentAds $tads, $pageTemplateId, $imageIdList, $text)
    {
        $pageName = 'SDK sample wechat page ' . uniqid();

        $pageElementsSpecList = [
            [
                'element_type' => 'CAROUSEL',
                'image_spec'   => [
                    'image_id_list' => $imageIdList,
                ],
            ],
            [
                'element_type' => 'BUTTON',
                'button_spec'  => [
                    'url'   => 'http://e.qq.com',
                    'title' => $text,
                ],
            ],
        ];
        $shareContentSpec = [
            'share_title'       => '分享标题',
            'share_description' => '分享内容',
        ];

        $page = $tads->wechatPages()
                     ->add([
                         'account_id'              => static::$ACCOUNT_ID,
                         'page_name'               => $pageName,
                         'page_template_id'        => $pageTemplateId,
                         'page_elements_spec_list' => $pageElementsSpecList,
                         'share_content_spec'      => $shareContentSpec,
                     ]);

        return $page->getPageId();
    }

    // 创建profile
    protected function AddProfile(TencentAds $tads, $promotedObjectType, $imageId)
    {
        $profile = $tads->profiles()
                        ->add([
                            'account_id'           => static::$ACCOUNT_ID,
                            'profile_name'         => 'SDK用例' . uniqid(),
                            'profile_type'         => 'PROFILE_TYPE_DEFINITION',
                            'promoted_object_type' => $promotedObjectType,
                            'head_image_id'        => $imageId,
                            'description'          => 'SDK sample',
                        ]);

        return $profile->getProfileId();
    }

    // 创建创意
    protected function AddAdcreative(
        TencentAds $tads,
        $adcreativeTemplateId,
        $campaignId,
        $promotedObjectType,
        $siteSet,
        $imageId,
        $adTitle,
        $adDescription,
        $adUrl,
        $profileId
    ) {
        $adcreativeName = 'SDK sample adcreative ' . uniqid();
        $adcreativeElements = [
            'image_list'  => [$imageId],
            'title'       => $adTitle,
            'description' => $adDescription,
        ];
        $pageType = 'PAGE_TYPE_DEFAULT';
        $pageSpec = [
            'page_url' => $adUrl,
        ];

        $adcreative = $tads->adcreatives()
                           ->add([
                               'account_id'             => static::$ACCOUNT_ID,
                               'campaign_id'            => $campaignId,
                               'adcreative_name'        => $adcreativeName,
                               'adcreative_template_id' => $adcreativeTemplateId,
                               'adcreative_elements'    => $adcreativeElements,
                               'promoted_object_type'   => $promotedObjectType,
                               'page_type'              => $pageType,
                               'page_spec'              => $pageSpec,
                               'site_set'               => $siteSet,
                               'profile_id'             => $profileId,
                           ]);
        $adcreativeId = $adcreative->getAdcreativeId();

        return $adcreativeId;
    }

    // 创建广告
    protected function AddAd(TencentAds $tads, $adgroupId, $adcreativeId)
    {
        $adName = 'SDK sample ad ' . uniqid();

        $ad = $tads->ads()
                   ->add([
                       'account_id'    => static::$ACCOUNT_ID,
                       'adgroup_id'    => $adgroupId,
                       'adcreative_id' => $adcreativeId,
                       'ad_name'       => $adName,
                   ]);
        $adId = $ad->getAdId();

        return $adId;
    }
}

if (basename($_SERVER['PHP_SELF']) == basename(__FILE__)) {
    try {
        $example = new AddLeadsAds();
        $example->init();
        $example->main();
    } catch (\Exception $e) {
        exit(-1);
    }
}
            
                package com.tencent.ads.examples.WechatAds;

import com.tencent.ads.ApiContextConfig;
import com.tencent.ads.ApiException;
import com.tencent.ads.TencentAds;
import com.tencent.ads.exception.TencentAdsResponseException;
import com.tencent.ads.exception.TencentAdsSDKException;
import com.tencent.ads.model.AdcreativeCreativeElementsMp;
import com.tencent.ads.model.AdcreativesAddRequest;
import com.tencent.ads.model.AdcreativesAddResponseData;
import com.tencent.ads.model.AdgroupsAddRequest;
import com.tencent.ads.model.AdgroupsAddResponseData;
import com.tencent.ads.model.AdsAddRequest;
import com.tencent.ads.model.AdsAddResponseData;
import com.tencent.ads.model.AgeStruct;
import com.tencent.ads.model.BillingEvent;
import com.tencent.ads.model.CampaignType;
import com.tencent.ads.model.CampaignsAddRequest;
import com.tencent.ads.model.CampaignsAddResponseData;
import com.tencent.ads.model.DestinationType;
import com.tencent.ads.model.GeoLocations;
import com.tencent.ads.model.ImagesAddResponseData;
import com.tencent.ads.model.OptimizationGoal;
import com.tencent.ads.model.PageSpec;
import com.tencent.ads.model.ProfileType;
import com.tencent.ads.model.ProfilesAddRequest;
import com.tencent.ads.model.ProfilesAddResponseData;
import com.tencent.ads.model.PromotedObjectType;
import com.tencent.ads.model.WriteTargetingSettingForAdgroup;
import com.tencent.ads.utils.SignatureUtils;
import java.io.File;
import java.text.SimpleDateFormat;
import java.util.Arrays;
import java.util.Calendar;
import java.util.Date;
import java.util.List;
import java.util.UUID;

/** 本文件提供了一个创建一个朋友圈线索收集广告的示例 */
public class AddLeadsAds {

  /** YOUR ACCESS TOKEN */
  public String ACCESS_TOKEN = "YOUR ACCESS TOKEN";
  /** YOUR ACCOUNT ID */
  public Long ACCOUNT_ID = 0L;
  /** 图片文件路径 */
  public String IMAGE_PATH = "YOUR AD IMAGE PATH"; // 450规格要求:800x450, <300K, png/jpg
  /** Profile图片文件路径 */
  public String IMAGE_PROFILE_PATH = "YOUR AD IMAGE PROFILE PATH"; // 200x200, <300K, png/jpg
  /** 朋友圈单图文 */
  public Long ADCREATIVE_TEMPLATE_ID = 450L;
  /** 广告标题,450规格要求:字数:1~10 */
  public String AD_TITLE = "YOUR AD TITLE";
  /** 广告文案,450规格要求:字数:1~30 */
  public String AD_DESCRIPTION = "YOUR AD DESCRIPTION";
  /** H5外链地址 */
  public String AD_URL = "YOUR AD PAGE URL";
  /** TencentAds */
  public TencentAds tencentAds;

  public void init() {
    this.tencentAds = TencentAds.getInstance();
    this.tencentAds.init(
        new ApiContextConfig().accessToken(ACCESS_TOKEN).isDebug(true)); // debug==true 会打印请求详细信息
    this.tencentAds.useSandbox(); // 默认使用沙箱环境,如果要请求线上,这里需要设为线上环境
  }

  public Long addLeadsAds() throws Exception {
    // 第一步,创建推广计划
    // CampaignType.NORMAL: 普通展示广告, PromotedObjectType.LEAD_AD:线索收集
    Long campaignId = addCampaign(CampaignType.NORMAL, PromotedObjectType.LEAD_AD);
    // 第二步,创建广告组,不允许使用定向包,因此在广告组里创建定向
    // 投放微信流量
    List<String> siteSet = Arrays.asList("SITE_SET_MOMENTS");
    Long adgroupId = addAdgroups(campaignId, PromotedObjectType.LEAD_AD, siteSet);
    // 第三步,上传素材
    String imageId = addImage(IMAGE_PATH);
    String imageIdLeads = addImage(IMAGE_PROFILE_PATH);
    Long profileId = addProfile(PromotedObjectType.LEAD_AD, imageIdLeads);
    // 第四步,创建创意
    Long adcreativeId =
        addAdcreative(
            ADCREATIVE_TEMPLATE_ID,
            AD_URL,
            PromotedObjectType.LEAD_AD,
            AD_TITLE,
            AD_DESCRIPTION,
            campaignId,
            Arrays.asList(imageId),
            siteSet,
            profileId);
    // 第五步,创建广告
    Long adId = addAd(adgroupId, adcreativeId);
    return adId;
  }

  /**
   * 创建推广计划
   *
   * @param campaignType 推广计划类型
   * @param promotedObjectType 推广目标类型
   * @return 推广计划id
   * @throws ApiException 异常
   */
  protected Long addCampaign(CampaignType campaignType, PromotedObjectType promotedObjectType)
      throws ApiException {
    CampaignsAddRequest campaignsAddRequest = new CampaignsAddRequest();
    campaignsAddRequest.setAccountId(ACCOUNT_ID);
    campaignsAddRequest.setCampaignName(
        "SDK sample campaign" + UUID.randomUUID().toString().substring(0, 6));
    campaignsAddRequest.setCampaignType(campaignType);
    campaignsAddRequest.setPromotedObjectType(promotedObjectType);
    campaignsAddRequest.setDailyBudget(0L);
    CampaignsAddResponseData responseData =
        tencentAds.campaigns().campaignsAdd(campaignsAddRequest);
    if (responseData != null) {
      return responseData.getCampaignId();
    }
    return null;
  }

  /**
   * 创建广告组
   *
   * @param campaignId 推广计划id
   * @param promotedObjectType 推广目标类型
   * @param siteSet 投放站点
   * @return 返回
   * @throws ApiException 异常
   */
  protected Long addAdgroups(
      Long campaignId, PromotedObjectType promotedObjectType, List<String> siteSet)
      throws ApiException {
    AdgroupsAddRequest data = new AdgroupsAddRequest();
    data.setAccountId(ACCOUNT_ID);
    data.setAdgroupName("SDK sample adgroup" + UUID.randomUUID().toString().substring(0, 6));
    data.setPromotedObjectType(promotedObjectType);
    // 开始投放日期和结束投放日期
    SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd");
    Date now = new Date();
    Calendar calendar = Calendar.getInstance();
    calendar.setTime(now);
    calendar.add(Calendar.DATE, +1);
    Date start = calendar.getTime();
    calendar.setTime(now);
    calendar.add(Calendar.DATE, +10);
    Date end = calendar.getTime();
    data.setBeginDate(df.format(start));
    data.setEndDate(df.format(end));
    // CPM
    data.setBillingEvent(BillingEvent.IMPRESSION);
    // 50元(单位为分)
    data.setBidAmount(5000L);
    // 优化目标展示
    data.setOptimizationGoal(OptimizationGoal.IMPRESSION);
    // 日预算10000元(单位为分)
    data.setDailyBudget(1000000L);
    // 全天投放
    String timeSeries =
        "11111111111111111111111111111111111111111111111111111111"
            + "1111111111111111111111111111111111111111111111111111111111111111111111"
            + "1111111111111111111111111111111111111111111111111111111111111111111111"
            + "1111111111111111111111111111111111111111111111111111111111111111111111"
            + "1111111111111111111111111111111111111111111111111111111111111111111111";
    data.setTimeSeries(timeSeries);
    data.setSiteSet(siteSet);
    WriteTargetingSettingForAdgroup targeting = new WriteTargetingSettingForAdgroup();
    // 年龄定向: 23~45岁, 性别定向:男性, 地域定向: 北京
    targeting
        .age(Arrays.asList(new AgeStruct().max(45L).min(23L)))
        .gender(Arrays.asList("MALE"))
        .geoLocation(
            new GeoLocations()
                .locationTypes(Arrays.asList("LIVE_IN"))
                .regions(Arrays.asList(110000L)));
    data.setTargeting(targeting);
    data.setCampaignId(campaignId);
    AdgroupsAddResponseData responseData = tencentAds.adgroups().adgroupsAdd(data);
    if (responseData != null) {
      return responseData.getAdgroupId();
    }
    return null;
  }

  /**
   * 添加图片文件
   *
   * @param imageFile 图片文件地址
   * @return 图片id
   * @throws Exception 异常
   */
  protected String addImage(String imageFile) throws Exception {
    ImagesAddResponseData responseData =
        tencentAds
            .images()
            .imagesAdd(
                ACCOUNT_ID,
                "UPLOAD_TYPE_FILE",
                SignatureUtils.getMD5Checksum(imageFile),
                new File(imageFile),
                null,
                null,
                null,
                null,
                null,
                null);
    if (responseData != null) {
      return responseData.getImageId();
    }
    return null;
  }

  /**
   * 创建朋友圈头像昵称跳转页
   *
   * @param promotedObjectType 推广目标类型
   * @param imageId 图片id
   * @return 朋友圈头像及昵称跳转页 id
   * @throws ApiException 异常
   */
  protected Long addProfile(PromotedObjectType promotedObjectType, String imageId)
      throws ApiException {
    ProfilesAddRequest addRequest = new ProfilesAddRequest();
    addRequest.setAccountId(ACCOUNT_ID);
    addRequest.setProfileName("SDKsample" + UUID.randomUUID().toString().substring(0, 4));
    addRequest.setProfileType(ProfileType.DEFINITION);
    addRequest.setPromotedObjectType(promotedObjectType);
    addRequest.setHeadImageId(imageId);
    addRequest.setDescription("SDKsample");
    ProfilesAddResponseData responseData = tencentAds.profiles().profilesAdd(addRequest);
    if (responseData != null) {
      return responseData.getProfileId();
    }
    return null;
  }

  /**
   * @param adcreativeTemplateId 创意规格 id
   * @param pageUrl 落地页 url
   * @param promotedObjectType 推广目标类型
   * @param creativeElementsTitle 创意元素标题
   * @param creativeElementsDesc 创意元素描述
   * @param campaignId 推广计划id
   * @param imageIdList 图片id列表
   * @param siteSet 投放站点
   * @param profileId 朋友圈头像昵称跳转页 id
   * @return 创意id
   * @throws ApiException 异常
   */
  protected Long addAdcreative(
      Long adcreativeTemplateId,
      String pageUrl,
      PromotedObjectType promotedObjectType,
      String creativeElementsTitle,
      String creativeElementsDesc,
      Long campaignId,
      List<String> imageIdList,
      List<String> siteSet,
      Long profileId)
      throws ApiException {
    AdcreativesAddRequest data = new AdcreativesAddRequest();
    data.setAccountId(ACCOUNT_ID);
    data.setAdcreativeName("SDK sample adcreative" + UUID.randomUUID().toString().substring(0, 6));
    data.setAdcreativeElements(
        new AdcreativeCreativeElementsMp()
            .imageList(imageIdList)
            .title(creativeElementsTitle)
            .description(creativeElementsDesc));
    data.setPageSpec(new PageSpec().pageUrl(pageUrl));
    data.setPageType(DestinationType.DEFAULT);
    data.setAdcreativeTemplateId(adcreativeTemplateId);
    data.setPromotedObjectType(promotedObjectType);
    data.setCampaignId(campaignId);
    data.setSiteSet(siteSet);
    data.setProfileId(profileId);
    AdcreativesAddResponseData responseData = tencentAds.adcreatives().adcreativesAdd(data);
    if (responseData != null) {
      return responseData.getAdcreativeId();
    }
    return null;
  }

  /**
   * 创建广告
   *
   * @param adgroupId 广告组id
   * @param adcreativeId 广告创意id
   * @return 广告id
   * @throws ApiException 异常
   */
  protected Long addAd(Long adgroupId, Long adcreativeId) throws ApiException {
    AdsAddRequest data = new AdsAddRequest();
    data.setAccountId(ACCOUNT_ID);
    data.setAdgroupId(adgroupId);
    data.setAdcreativeId(adcreativeId);
    data.setAdName("SDK sample ad" + UUID.randomUUID().toString().substring(0, 6));
    AdsAddResponseData responseData = tencentAds.ads().adsAdd(data);
    if (responseData != null) {
      return responseData.getAdId();
    }
    return null;
  }

  public static void main(String[] args) {
    try {
      AddLeadsAds addLeadsAds = new AddLeadsAds();
      addLeadsAds.init();
      Long adId = addLeadsAds.addLeadsAds();
    } catch (TencentAdsResponseException e) {
      e.printStackTrace();
    } catch (TencentAdsSDKException e) {
      e.printStackTrace();
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}