蹊径落地页 API

本节将为您介绍蹊径落地页的相关接口。

在了解下方接口前，需要理解落地页制作工具运营模板和私有模板的概念，需要先获取到合适的运营或私有模板 id，此后，调用获取模板接口，根据返回的模板进行数据填充，再调用创建和送审接口，需要时，可以调用删除接口进行删除。

模板 id 的获取:

制作端, 使用某个模板, url 上有 templateId 字段

公共请求参数

公共请求参数是指每一个接口都需要使用到的参数。详情参考，代码案例参考。

参数名称 参数类型
access_token 授权令牌，完成 OAuth 2.0 授权后获得，参考【授权认证】章节
timestamp 当前的时间戳，单位为秒，允许客户端请求最大时间误差为 300 秒。MarketingAPI 所使用的时间戳，若无特殊说明，均为秒级时间戳 MarketingAPI 所使用的时区为 GMT+8，例如当时间戳为 1494840119 时，表示 2018-05-15 17:21:59
nonce 随机字串标识，不超过 32 个字符，由调用方自行生成，需保证全局唯一性
fields get 接口增加 fields 字段，用于指定返回参数的字段列表，为选填字段。如不填写，则根据默认值进行返回

获取落地页

请求地址:
xijing_page/list

请求方法:
GET

请求参数:

名称 类型 描述
account_id integer 推广帐号 id，有操作权限的帐号 id，包括代理商和广告主帐号 id，必填
page_id integer 蹊径落地页 id，非必填
page_name string 蹊径落地页名称，非必填
page_type string[] 蹊径落地页类型，非必填
page_status string[] 蹊径落地页状态，非必填
page_publish_status string[] 蹊径落地页发布状态，非必填
page_last_modify_start_time string 蹊径落地页最后修改时间，查询时间开始范围，非必填
page_last_modify_end_time string 蹊径落地页最后修改时间，查询时间结束范围，非必填
page_size integer 查询数据量大小，非必填
page_index integer 查询数据量偏移，非必填

请求实例:

curl -G 'https://api.e.qq.com/v1.1/xijing_template/get?access_token=<ACCESS_TOKEN>&timestamp=<TIMESTAMP>&nonce=<NONCE>&account_id=<ACCOUNTID>'

应答示例:

{
  "code": 0,
  "message": "",
  "data": {
    "total_pages": 322, // 落地页总数
    "page_size": 10, // 查询展示数据量
    "page_index": 1, // 查询展示偏移量
    "list": [ // 落地页列表
      {
        "page_id": 1003124,
        "page_name": "pageName1",
        "page_type": "XJ_ANDROID_APP_H5",
        "page_publish_status": "LANDING_PAGE_STATUS_UNPUBLISH",
        "page_status": "LANDING_PAGE_STATUS_EDITING",
        "page_last_modify_time": "2020-08-04T10:04:22",
      }
    ],
    "mobile_app_id": "" // app id
  }
}

注：

各落地页仅展示该落地页“线上版本”的状态，对于副本的状态未予以展示。
落地页副本：编辑已发布状态的落地页并保存或送审时，系统会生成一份落地页副本。

落地页类型说明

类型 说明
XJ_DEFAULT_H5 默认落地页
XJ_ANDROID_APP_H5 Android应用落地页
XJ_IOS_APP_H5 IOS应用落地页
XJ_WEBSITE_H5 网页落地页
XJ_ANDROID_APP_NATIVE android app原生落地页
XJ_IOS_APP_NATIVE ios app原生落地页
XJ_WEBSITE_NATIVE 原生落地页
XJ_FENGLING_LBS 风铃电商

以下是page_publish_status的说明

落地页发布状态说明

类型 说明
LANDING_PAGE_STATUS_UNPUBLISH 草稿：“保存”和“未送审”的落地页处于草稿状态，不可用于广告投放，只有“送审”后才会进入落地页审核。
LANDING_PAGE_STATUS_PUBLISHED 已发布：审核通过的落地页即处于已发布状态。
LANDING_PAGE_STATUS_OFFLINE 审核下线：已审核通过的落地页，可能因为侵权、被投诉或不符合新规等原因被审核人员下线。修改后可重新送审。
LANDING_PAGE_STATUS_DELETING 落地页删除中
LANDING_PAGE_STATUS_DELETED 落地页已删除

以下是page_status的说明

落地页状态说明

类型 说明
LANDING_PAGE_STATUS_EDITING 编辑中
LANDING_PAGE_STATUS_PENDING 审核中：送审后，审核人员一般需要2-3小时完成审核，这期间的落地页处于审核状态。
LANDING_PAGE_STATUS_APPROVED 审核通过
LANDING_PAGE_STATUS_REJECTED 审核不过：落地页存在违规内容，审核拒绝。修改后可重新送审。
LANDING_PAGE_STATUS_DELETED 操作版本已删除

获取模板

请求地址:
xijing_template/get

请求方法:
GET

请求参数:

名称 类型 描述
account_id integer 推广帐号 id，有操作权限的帐号 id，包括代理商和广告主帐号 id
template_id integer 蹊径落地页模板 id，公共的营销模板 id，或有权限的私有模板 id

请求实例:

curl -G 'https://api.e.qq.com/v1.1/xijing_template/get?access_token=<ACCESS_TOKEN>&timestamp=<TIMESTAMP>&nonce=<NONCE>' \
-d 'account_id=<ACCOUNT_ID>' \
-d 'template_id=<TEMPLATE_ID>'

应答示例:

{
  "code": 0,
  "message": "",
  "data": {
    "page_template_id": 1006, // 模板 id
    "page_type": "PAGE_TYPE_XIJING_ANDROID", // 模板类型，支持 PAGE_TYPE_XIJING_ANDROID、PAGE_TYPE_XIJING_IOS、PAGE_TYPE_XIJING_WEBSITE
    "page_name": "", // 落地页名称，用于管理
    "page_title": "", // 落地页标题，用于展示
    "component_spec_list": [ // 组件列表
      {
        "type": "COMPONENT_TYPE_IMAGES",
        "image_list_spec": {
          "image_list": [
            {
              "image_id": ""
            }
          ]
        }
      },
      {
        "type": "COMPONENT_TYPE_BUTTON",
        "button_spec": {
          "text": ""
        }
      }
    ],
    "mobile_app_id": "" // app id
  }
}

以上是获取到的模板，我们需要填充模板的空白字段，此后，将填充好的模板+数据用于创建接口

以下是模板的详细解释

模板整体结构

{
  "code": 0,
  "message": "",
  "data": {
    "page_template_id": 1006, // 模板 id
    "page_type": "PAGE_TYPE_XIJING_ANDROID", // 模板类型，支持 PAGE_TYPE_XIJING_ANDROID、PAGE_TYPE_XIJING_IOS、PAGE_TYPE_XIJING_WEBSITE
    "page_name": "", // 落地页名称，用于管理
    "page_title": "", // 落地页标题，用于展示
    "component_spec_list": [ // 组件列表
    ],
    "mobile_app_id": "" // Android 或 iOS app id
  }
}

PAGE_TYPE_XIJING_WEBSITE 类型的模板不会返回 mobile_app_id

page_type

page_type 枚举值如下

component_spec_list

video_spec - 视频

支持 PAGE_TYPE_XIJING_WEBSITE、PAGE_TYPE_XIJING_ANDROID、PAGE_TYPE_XIJING_IOS

{
  "type": "COMPONENT_TYPE_VIDEO",
  "video_spec": {
    "video_id": "" // 调用 Marketing API 视频上传接口返回的视频 id
  }
}

text_spec - 文本

{
  "type": "COMPONENT_TYPE_TEXT",
  "text_spec": {
    "text": "", // 普通文本
    "rich_text": "" // 富文本
  }
}

text 和 rich_text 字段互斥，根据模板的设置，只会返回其中一个

image_list_spec - 多图

支持 PAGE_TYPE_XIJING_WEBSITE、PAGE_TYPE_XIJING_ANDROID、PAGE_TYPE_XIJING_IOS

{
  "type": "COMPONENT_TYPE_IMAGES",
  "image_list_spec": {
    "image_list": [
      {
        "image_id": "", // 调用 Marketing API 图片上传接口返回的图片 id
        "hot_area": [
          // hot_area 字段只会在 PAGE_TYPE_XIJING_WEBSITE 类型的落地页设置了热区之后出现，因 PAGE_TYPE_XIJING_ANDROID、PAGE_TYPE_XIJING_IOS 类型的落地页的热区不需要设置 url，所以没有该字段
          {
            "url": "" // 热区跳转的外部链接
          },
          {}, // 如果热区不是跳转到外部链接，则返回空对象
          {
            "url": ""
          }
        ]
      },
      {
        "image_id": ""
      }
    ]
  }
}

button_spec - 下载按钮 (按钮)

支持 PAGE_TYPE_XIJING_WEBSITE、PAGE_TYPE_XIJING_ANDROID、PAGE_TYPE_XIJING_IOS

{
  "type": "COMPONENT_TYPE_BUTTON",
  "button_spec": {
    "text": "", // 按钮文案
    "url": "" // url 字段只在 PAGE_TYPE_XIJING_WEBSITE 类型的落地页出现，PAGE_TYPE_XIJING_ANDROID、PAGE_TYPE_XIJING_IOS 类型的落地页不需要 url，所以不返回
  }
}

app_info_button_spec - 底部下载图

支持 PAGE_TYPE_XIJING_ANDROID、PAGE_TYPE_XIJING_IOS

{
  "type": "COMPONENT_TYPE_APP_INFO_BUTTON",
  "app_info_button_spec": {
    "text": "" // 组件中部的 APP 描述
  }
}

fixed_button_spec - 固定按钮

支持 PAGE_TYPE_XIJING_ANDROID、PAGE_TYPE_XIJING_IOS

{
  "type": "COMPONENT_TYPE_FIXED_BUTTON",
  "fixed_button_spec": {
    "desc": "", // 下载描述字段 (app log 的样式)
    "text": "" // 下载按钮文案 (一个按钮的样式)
  }
}

desc、text 两个字段互斥，根据模板设置，只会返回其中一个

game_demo_spec - 试玩

{
    "type": "COMPONENT_TYPE_GAME_DEMO",
    "game_demo_spec": {
        "game_url": "", // 游戏链接, https 协议, 必填
        "cover_image_id": "", // 封面图, 如果是空字符串, 则采用模板的封面图, 如果模板没有封面图, 则保持没有封面图, 如果指定图片 id, 则以该字段为主
        "button_text": "立即下载", // 普通下载按钮样式对应的下载按钮文案, 最大字符数: 20
        "button_desc": "下载描述", // 卡片样式(左 app logo, 中间文字, 右边按钮)对应的下载描述, 最大字符数: 18
        "wait_time": 3 // 按钮入场等待时间, 单位: 秒
    }
}

button_text 与 button_desc 互斥, 根据模板设置只会返回一个

button_text, button_desc, wait_time 只有在启用了 "下载按钮" 开关, 才会返回

link_spec - 链接

支持 PAGE_TYPE_XIJING_WEBSITE

{
  "type": "COMPONENT_TYPE_LINK",
  "link_spec": {
    "text": "", // 链接文本
    "url": "" // 链接地址
  }
}

layer_card_spec - 浮层页卡

{
  "type": "COMPONENT_TYPE_LAYER_CARD",
  "layer_card_spec": {
    "text": "", // 浮层页卡下载按钮 必填
    "description": "", // app应用描述 必填
    "image_list": [
      "" // 浮层页卡轮播图图片adsId
    ]
  }
}

创建接口

请求地址:
xijing_page/add

请求方法:
POST

请求参数:

名称 类型 描述
account_id integer 推广帐号 id，有操作权限的帐号 id，包括代理商和广告主帐号 id
is_auto_submit integer 1 为自动送审，其它值或不填，则只创建，后期自行调用接口送审
pages struct[] 模板填充数据列表，每个元素为填充完成的模板 
{
  "account_id": 20458,
  "is_auto_submit": 1, // 是否自动送审
  "pages": [
    {
      "page_template_id": 1003, // 模板 id，保持与模板一致
      "page_type": "PAGE_TYPE_XIJING_ANDROID", // 落地页类型，保持与模板一致
      "page_name": "落地页名称", // 落地页名称, 用于管理
      "page_title": "落地页标题", // 落地页标题，用于展示
      "component_spec_list": [], // 组件列表
      "mobile_app_id": "" // app id
    }
  ]
}

请求参数示例(application/json):

{
  "account_id": 20458,
  "pages": [
    {
      "page_template_id": 1006,
      "page_type": "PAGE_TYPE_XIJING_ANDROID",
      "page_name": "落地页名称 - 用于管理",
      "page_title": "落地页标题 - 用于展示",
      "component_spec_list": [
        {
          "type": "COMPONENT_TYPE_VIDEO",
          "video_spec": {
            "video_id": "1540"
          }
        },
        {
          "type": "COMPONENT_TYPE_TEXT",
          "text_spec": {
            "text": "hi 蹊径落地页"
          }
        },
        {
          "type": "COMPONENT_TYPE_IMAGES",
          "image_list_spec": {
            "image_list": [
              {
                "image_id": "1000437"
              }
            ]
          }
        },
        {
          "type": "COMPONENT_TYPE_BUTTON",
          "button_spec": {
            "text": "123"
          }
        },
        {
          "type": "COMPONENT_TYPE_APP_INFO_BUTTON",
          "app_info_button_spec": {
            "text": "底部下载图的描述"
          }
        },
        {
          "type": "COMPONENT_TYPE_FIXED_BUTTON",
          "fixed_button_spec": {
            "desc": "下载描述文案"
          }
        }
      ],
      "mobile_app_id": "1104790111"
    }
  ]
}

应答示例:

{
  "code": 0, // 0 为成功，68031 为失败，68030 为部分失败
  "message": "",
  "data": [
    {
      "id": "576460752303438398",//  落地页服务id
      "landingPageId": "523034383985764607",// 落地页Id
      "message": "操作成功",
      "code": 0 // 0 为成功
    }
  ]
}

基于组件创建接口

请求地址:
xijing_page_by_components/add

请求方法:
POST

请求参数:

名称 类型 描述
account_id integer 推广帐号 id，有操作权限的帐号 id，包括代理商和广告主帐号 id
is_auto_submit integer 1 为自动送审，其它值或不填，则只创建，后期可自行调用接口送审
pages struct[] 落地页配置信息列表，每个元素为各个页面的配置信息

请求结构体说明:

{
  "account_id": 20458,
  "is_auto_submit": 1, // 是否自动送审
  "pages": [
    {
      "page_type": "PAGE_TYPE_XIJING_ANDROID", // 落地页类型，目前只支持安卓落地页
      "page_name": "落地页名称", // 落地页名称, 用于管理
      "page_title": "落地页标题", // 落地页标题，用于展示
      "mobile_app_id": "", // app id
      "bg_color": "rgba(189, 16, 224, 1)", // 落地页背景色
      "bg_image_id": "", // 调用 Marketing API 图片上传接口返回的图片 id
      "component_spec_list": [] // 组件列表,当前只支持固定按钮组件及多图组件
    }
  ]
}

多图组件配置说明:


  {
    "type": "COMPONENT_TYPE_IMAGES", // 组件类型
    "image_list_spec": {
      "image_list": [
        {
          "image_id": "1000437", // 调用 Marketing API 图片上传接口返回的图片 id
          /* 设置热区，最多设置3个 */
          "hot_area": [
            {
              
              /* 以下属性不设置均为示例所示默认值，单位均为% */
              /* 此处会校验合法性，不合法范围判断：
              * top + height > 100
              * width + left > 100
              * width、height、top、left存在小于0的值
              */
              
              /* 设置热区大小 */
              "width": 30, // 宽度
              "height": 30, // 高度
              /* 设置热区位置 */
              "top": 20, // 与顶部距离
              "left": 20 // 与左侧距离
            }
          ],
          /* 设置图片边距，以下属性不设置均为示例所示默认值，单位均为px */
          "padding": [
            {
              "top": 0,
              "right": 0,
              "bottom": 0,
              "left": 0
            }
          ],
          /* 进度条样式，不设置为示例所示默认值 */
          "progress_bar": [
            {
              "color": "rgb(255, 255, 255)",
              "backgroundColor": "#1890ff"
            }
          ]
        }
      ]
    }
  }

固定组件配置说明:


  {
    "type": "COMPONENT_TYPE_FIXED_BUTTON", // 组件类型
    "fixed_button_spec": {
      "button_style": "fixedBtn-1", //  按钮类型：fixedBtn-1(app信息类型), fixedBtn-2(纯文案类型), fixedBtn-3(自定义图片类型)
      /* 通用配置 */
      "common_setting": {
        "position": "bottom", //  按钮位置：top,bottom
        "white_space": 80, //  留白，防止底部内容被遮挡[0,200]
        "distance_to_view_port": 1 //  position为top:据viewport顶部的高度，position为bottom:据viewport底部的的距离[0,100]
      },
      
      /* 各类型按钮配置
       * btn_setting为不同类型的固定按钮的单独配置
       * 依据button_style的类型选择下述对应的一个配置信息即可
      */
      
      /* fixedBtn-1(app信息类型)配置 */
      "btn_setting": {
        "desc": "是兄弟就来", //  app类型描述文案,minLength：0,maxLength:18
        "background_color": "#1890ff", //  下载点击按钮背景色
        "color": "rgb(255, 255, 255)" //  下载点击文字颜色
      },
      /* fixedBtn-2(纯文案类型)配置 */
      "btn_setting": {
        "text": "xxxx", //  下载按钮文本,minLength：1,maxLength:18
        "background_color": "#1890ff", //  下载点击按钮背景色
        "color": "rgb(255, 255, 255)" //  下载点击文字颜色
      },
      /* fixedBtn-3(自定义图片类型)配置 */
      "btn_setting": {
        "align": "center", //  图片居中位置：left, center, right
        "image_id": "", //  调用 Marketing API 图片上传接口返回的图片 id
        "wrapper": {
          "padding_left": 0, //  图片左边距[0,100]
          "padding_right": 0 //  图片右边距[0,100]
        }
      }
    }
  }

试玩组件配置说明:


  // 试玩组件与其他组件不兼容
  {
    "type": "COMPONENT_TYPE_GAME_DEMO", // 组件类型
    "game_demo_spec": {
      "game_url": "https://game_demo/url"
      "cover_image_id": "1000437", // 调用 Marketing API 图片上传接口返回的图片 id
      "wait_time": 10, // 入场等待时间
      "game_download": false, // 启用游戏内下载
      "btn_download": true, // 启用按钮下载
      "btn_style": "downLoadBtn", //  按钮类型：downLoadBtn,fixedBtn-1
      
      /* 各类型按钮配置
       * btn_setting为不同类型的固定按钮的单独配置
       * btn_setting依据button_style的类型选择下述对应的一个配置信息即可
      */
      
      /* downLoadBtn(纯文案类型)配置 */
      /* fixedBtn-1(app信息类型)配置 */
      "btn_setting": {
        "text": "downLoadBtn下载文案", //  下载文案,minLength：0,maxLength:20
        "desc": "fixedBtn-1App描述", //  app类型描述文案,minLength：0,maxLength:18
        "background_color": "#1890ff", //  下载点击按钮背景色
        "color": "rgb(255, 255, 255)" //  下载点击文字颜色
        "font_size": 16 //  文字大小：16, 18, 20, 22
        "border_radius": 4 //  圆角: [0,30]
        "top": 0 //  纵向位置: [0,100]
        "height": 40 //  仅在类型为downloadBtn时有效：高度: [30,60]
        /* left + width <= 100 */
        "left": 40 //  横向位置: fixedBtn-1[0,30]，downloadBtn[0,80]
        "width": 40 //  宽度: fixedBtn-1[70,100]，downloadBtn[20,100]
      }
    }
  }

请求参数示例(application/json):

{
    "account_id": 20458,
    "is_auto_submit": 1,
    "pages": [
      {
        "page_type": "PAGE_TYPE_XIJING_ANDROID",
        "mobile_app_id": "应用Id",
        "page_name": "落地页名称 - 用于管理",
        "page_title": "落地页标题 - 用于展示",
        "bg_color": "rgba(189, 16, 224, 1)",
        "bg_image_id": "",
        "component_spec_list": [
          {
            "type": "COMPONENT_TYPE_IMAGES",
            "image_list_spec": {
              "image_list": [
                {
                  "image_id": "1000437",
                  "hot_area": [
                    {
                      "width": 30,
                      "height": 30,
                      "top": 20,
                      "left": 20
                    }
                  ],
                  "padding": [
                    {
                      "top": 0,
                      "right": 0,
                      "bottom": 0,
                      "left": 0
                    }
                  ],
                  "progress_bar": [
                    {
                      "color": "rgb(255, 255, 255)",
                      "backgroundColor": "#1890ff"
                    }
                  ]
                }
              ]
            }
          },
          {
            "type": "COMPONENT_TYPE_FIXED_BUTTON",
            "fixed_button_spec": {
              "button_style": "fixedBtn-1",
              "common_setting": {
                "position": "bottom",
                "white_space": 80,
                "distance_to_view_port": 14
              },
              "btn_setting": {
                "desc": "是兄弟就来",
                "background_color": "#1890ff",
                "color": "rgb(255, 255, 255)"
              }
            }
          }
        ]
      }
    ]
  }

应答示例:

{
  "code": 0, // 0 为成功，68031 为失败，68030 为部分失败
  "message": "",
  "data": [
    {
      "id": "576460752303438398",//  落地页服务id
      "landingPageId": "523034383985764607",// 落地页Id
      "message": "操作成功",
      "code": 0 // 0 为成功
    }
  ]
}

送审接口

请求地址:
xijing_page/update

请求方法:
POST

请求参数示例(application/json):

{
  account_id: 123456,
  is_submitted_for_review: true,
  page_id_list: ["576460752303438398", "576460752303438399", "..."]
}

应答示例:

{
  "code": 0, // 0 为送审成功，68033 为送审失败，68032 为部分送审失败
  "message": "",
  "data": [
    {
      "id": "576460752303438398",
      "message": "操作成功",
      "code": 0 // 0 为成功，其它值为失败
    },
    {
      "id": "576460752303438399",
      "message": "操作成功",
      "code": 0
    },
    {
      "id": "...",
      "message": "操作成功",
      "code": 0
    }
  ]
}

删除接口

请求地址:
xijing_page/delete

请求方法:
POST

请求参示例(application/json)

{
  "account_id": 123456,
  "page_id_list": ["576460752303438398", "576460752303438399", "..."]
}

应答示例:

{
  "code": 0, // 0 为删除成功，68035 为删除失败，68034 为部分删除失败
  "message": "",
  "data": [
    {
      "id": "576460752303438398",
      "message": "操作成功",
      "code": 0 // 0 为成功，其它值为失败
    },
    {
      "id": "576460752303438399",
      "message": "操作成功",
      "code": 0
    },
    {
      "id": "...",
      "message": "操作成功",
      "code": 0
    }
  ]
}