MW Logo

Magic Window 内容相关API文档

魔窗内容分发API接口文档V2.0      内容推荐标签



Token获取API

所有内容相关API调用需要先根据在魔窗管理后台(http://mgnt.magicwindow.cn)申请到的account_key和secret_code获取token,token默认有效时间为3小时

示例调用


        POST /token
        Host: https://api.mlinks.cc
        Content-Type: application/json;charset=utf-8
        Cache-Control: no-cache
        {
            “account_key": “YOUR_ACCOUNT_KEY_FROM_MAGIC_WINDOW",
            “secret_code": “YOUR_SECRET_CODE_FROM_MAGIC_WINDOW"
        }
    

请求说明

字段 类型 是否必须 备注
account_key string Yes 魔窗后台获取
secret_code string Yes 魔窗后台获取

请求说明

登录魔窗后台点击右上角,进入技术设置,查看“数据接口参数信息”获取account_key和secret_code。

返回示例


        {
            "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIwMTE3NTQ4MzU1ZWM0ZGI5OWQwNjEzNzJmYjkzYWM0YiIsImlzX2FwaV91c2VyIjoiYXBpX3VzZXIiLCJleHAiOjE0Nzc2ODI3NzMsImlhdCI6MTQ3NzY3MTk3M30.Q5qgLXdK008fghnlwXIAVNBt64bsPqu18sP8ueCGHFM",
            "msg": "Success",
            "expires_in": 10800
        }
    

内容发送API

内容发送包括提交新增内容和修改已发送内容,两种调用使用相同的API。同一个账号 (account_key)下的产品(product_key)下的内容ID(content_id)唯一标识该内容,魔窗内容库(Magic Window Content Repository)根据API 请求时间更新该唯一内容。 

示例调用


        POST /api/v2/content/upsert
        Host: https://api.mlinks.cc
        Content-Type: application/json;charset=utf-8
        Magic-Token: 上述鉴权API获取的token
        Account-Key: 获取token使用到的acount key
        Product-Key: 内容所对应产品的key
        Cache-Control: no-cache 
        {
            "count": 2,
            "contents": [{
                "content_id": "c10856862707196",
                "content": "
                <m:h3 mlink="http://a.mlink.cc/AAba">这是一个h3的例子</m:h3>
                <m:img src="http://img.magicwindow.cn/abc1.png" />
                <m:p text-indent="2em">这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落</m:p>
                <m:img src="http://img.magicwindow.cn/abc2.png" />
                <m:p>测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二</m:p>
                ",
                "rendering_type": "complex",
                "content_image_uri":"http://mstore.b0.upaiyun.com/products/10856_giuseppe/20160701/9371a5cfc438e8ec78b9a497d6379e78b95f39e8.jpg",
                "image_uri":"http://mstore.b0.upaiyun.com/products/10856_giuseppe/20160701/9371a5cfc438e8ec78b9a497d6379e78b95f39e8.jpg",
                "title": "中邦运动鞋THE SHARK 5.0",
                "shorten_uri": "http://mstore.b0.upaiyun.com/product",
                "long_title": "【OFashion迷橙】国庆惊喜价!16新款新底中邦运动鞋THE SHARK 5.0",
                "product": {
                    "audience": "年轻女性",
                    "brand": "Giuseppe Zanotti Design",
                    "color": "yellow",
                    "description": "Giuseppe Zanotti Design 运动鞋 Sneaker 酷感运动",
                    "designer": "Giuseppe Zanotti",
                    "made_in": "澳大利亚-墨尔本",
                    "name": "Giuseppe Zanotti Design 运动鞋",
                    "picture":"http://mstore.b0.upaiyun.com/products/10856_giuseppe/20160701/9371a5cfc438e8ec78b9a497d6379e78b95f39e8.jpg",
                    "price_range": "1000-2000"
                },
                "ref_content_ids": [
                    "c10856862707193",
                    "c10856862707194",
                    "c10856862707195"
                ],
                "summary": "商品标签:  Giuseppe Zanotti Design 运动鞋 Sneaker 酷感运动",
                "tags": [
                    "电商",
                    "购物",
                    "m:tag1",
                    "m:tag2"
                ],
            }, {
                "rendering_type": "video",
                "content": "
                <m:h3 mlink="http://a.mlink.cc/AAba">这是一个h3的例子</m:h3>
                <m:img src="http://img.magicwindow.cn/abc1.png" />
                <m:p text-indent="2em">这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落</m:p>
                <m:img src="http://img.magicwindow.cn/abc2.png" />
                <m:p>测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二</m:p>",
                "content_id": "c10856862707196",
                "content_image_uri": "http://mstore.b0.upaiyun.com/pic/10856.jpg",
                "image_uri": "http://mstore.b0.upaiyun.com/pic/108563435.jpg",
                "title": "中邦运动鞋THE SHARK 5.0",
                "long_title": "【OFashion迷橙】国庆惊喜价!16新款新底中邦运动鞋THE SHARK 5.0",
                "multi_media": {
                    "media_type": "text",
                    "title": "text",
                    "artist": "text",
                    "album": "text",
                    "published_year": "2016",
                    "track": "text",
                    "genre": "text",
                    "media_uri": "text",
                    "duration": "1:29:58",
                    "comment": "text"
                },
                "summary": "16新款新底中邦运动鞋THE SHARK",
                "tags": [
                    "电商","购物"
                ]
            }]
        }
    

使用curl的示例调用


        curl -X POST -H "Content-Type: application/json;charset=utf-8" -H "Magic-Token: the-magic-token" -H "Account-Key: the-account-key" -H "Product-Key: the-product-key" -H "Cache-Control: no-cache"  -d '{
            "count": 2,
            "contents": [{
                "content_id": "c10856862707196",
                "content": "
                <m:h3 mlink="http://a.mlink.cc/AAba">这是一个h3的例子</m:h3>
                <m:img src="http://img.magicwindow.cn/abc1.png" />
                <m:p text-indent="2em">这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落</m:p>
                <m:img src="http://img.magicwindow.cn/abc2.png" />
                <m:p>测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二</m:p>",
                "rendering_type": "complex",
                "content_image_uri":"http://mstore.b0.upaiyun.com/products/10856_giuseppe/20160701/9371a5cfc438e8ec78b9a497d6379e78b95f39e8.jpg",
                "image_uri":"http://mstore.b0.upaiyun.com/products/10856_giuseppe/20160701/9371a5cfc438e8ec78b9a497d6379e78b95f39e8.jpg",
                "title": "中邦运动鞋THE SHARK 5.0",
                "shorten_uri": "http://mstore.b0.upaiyun.com/product",
                "long_title": "【OFashion迷橙】国庆惊喜价!16新款新底中邦运动鞋THE SHARK 5.0",
                "product": {
                    "audience": "年轻女性",
                    "brand": "Giuseppe Zanotti Design",
                    "color": "yellow",
                    "description": "Giuseppe Zanotti Design 运动鞋 Sneaker 酷感运动",
                    "designer": "Giuseppe Zanotti",
                    "made_in": "澳大利亚-墨尔本",
                    "name": "Giuseppe Zanotti Design 运动鞋",
                    "picture":"http://mstore.b0.upaiyun.com/products/10856_giuseppe/20160701/9371a5cfc438e8ec78b9a497d6379e78b95f39e8.jpg",
                    "price_range": "1000-2000"
                },
                "ref_content_ids": [
                    "c10856862707193",
                    "c10856862707194",
                    "c10856862707195"
                ],
                "summary": "商品标签:  Giuseppe Zanotti Design 运动鞋 Sneaker 酷感运动",
                "tags": [
                    "电商",
                    "购物",
                    "m:tag1",
                    "m:tag2"
                ],
            }, {
                "render_type": "video",
                "content": "
        <m:p text-indent="2em">这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落</m:p>
                <m:img src="http://img.magicwindow.cn/abc2.png" />",
                "content_id": "c10856862707196",
                "content_image_uri":"http://mstore.b0.upaiyun.com/products/10856_giuseppe/20160701/9371a5cfc438e8ec78b9a497d6379e78b95f39e8.jpg",
                "image_uri":"http://mstore.b0.upaiyun.com/products/10856_giuseppe/20160701/9371a5cfc438e8ec78b9a497d6379e78b95f39e8.jpg",
                "title": "中邦运动鞋THE SHARK 5.0",
                "long_title": "【OFashion迷橙】国庆惊喜价!16新款新底中邦运动鞋THE SHARK 5.0",
                "multi_media": {
                    "media_type": "text",
                    "title": "text",
                    "artist": "text",
                    "album": "text",
                    "published_year": 2016,
                    "track": "text",
                    "genre": "text",
                    "media_uri": "text",
                    "duration": "1:29:58",
                    "comment": "text"
                },
                "summary": "16新款新底中邦运动鞋THE SHARK",
                "tags": [
                    "电商",
                ],
            }]
        }' "https://api.mlinks.cc/api/v2/content/upsert"
    

请求说明

字段 成员 成员 类型 是否必须 默认值 描述 备注
count number yes 本次http调用中发送的内容条数
contents Array yes
content_id string yes 用来表示该内容的唯一编码
authorized_to object yes {"mw": true} 是否授权 {“mw”: true} 即授权投放, {"mw":false}即测试数据,未授权
rendering_type string yes complex 内容渲染类型 可选类型为视频(video),音频(audio),图文(complex),电商(e-commerce),书籍(book)
content string yes 具体内容 ①支持简单的html。以防排列混乱,会过滤链接及外部引用的样式。Html白名单参考文末【内容HTML白名单】。
②同时支持简单的图文混排,具体格式请参考文末【图文混排格式】
title string yes 内容标题 最长不超过27个半角字符
long_title string yes 内容长标题 最长不超过50个半角字符
image_uri string yes 在分发平台曝光的内容图片uri 建议160x120,大小不要超过20K
content_image_uri string yes 在内容中间页里显示的主图uri 会做自适应。若选用图文混排页面渲染类型时,非必填
shorten_uri string yes 该内容对应的魔窗mLink短链 因为每个内容都对应app内的一个内容页,为了实现一键唤醒,需要在内容中指明该内容对应的一键唤醒短链,并且再创建短链的同时,选择内容分发平台的渠道,比如新浪,参照下图。 该短链需要拼接上表明该内容的内容id,比http://a.mlinks.cc/Azdj?content_id=123
summary string no 内容摘要 建议不要超过35个字符
ref_content_ids array no 关联的内容Id
tags array yes 标签 参照文档《内容推荐标签》,标签为必传,用于内容匹配。其中标签前面带上"m:"标记的标签如“m:奢侈品"会供管理后台做管理分组用,建议上传,方便内容管理。
product object no 若内容为电商产品属性,请填写product对象对应字段 如果内容涉及具体电商产品,请在product对象中填写具体信息
price_range string yes 价格,价格范围
audience string no 营销对象
brand string no 品牌
color string no 颜色
description string no 产品描述
designer string no 设计师
made_in string no 产地
name string no 名称
picture string no 图片uri 如果有多个图片uri,则以逗号分割
multi_media object no 若内容为多媒体属性,请填multi_media对象对应字段 如果内容涉及到多媒体内容,请在multi_media对象中填写具体信息
media_type string yes 媒体文件类型 支持audio,video
media_uri string yes 媒体文件地址 媒体文件的url地址
title string no 媒体文件标题
artist string no 作者 媒体文件的作者(比如歌曲的演唱者、有声读物的作者等)
album string no 媒体文件所属专辑 专辑名称
published_year string no 发行年份
track string no 音轨
genre string no 风格类型
duration string no 播放时长,单位:秒
comment string no 评论
book object no 若内容类型为图书性质,请填写book对象对应字段 如果内容涉及到书籍内容,请在multi_media对象中填写具体信息
name string yes 书籍名称
author string yes 作者
genre string yes 书籍风格分类,常见分类如科幻,武侠等
description string no 描述性信息
isbn string no isbn 编码
edition string no 发行第几版
award string no 获奖信息
copyright string no 版权信息
in_language string no 书籍语言
keywords string no
publisher string no 发行商
published_date string no 发行时间
modified_date string no 更新时间,常见于网络连载小说
number_of_pages string no 页数
number_of_words string no 字数
translator string no 翻译者
comment string no 书籍相关评论

返回说明

该API默认将接收的内容存储起来,不做及时验证处理,请使用下面提到的内容验证API获取内容发送情况报告

内容删除API

示例调用


        POST /api/v2/content/delete
        Host: https://api.mlinks.cc
        Content-Type: application/json;charset=utf-8
        Magic-Token: 上述鉴权API获取的token
        Account-Key: 获取token使用到的acount key
        Product-Key: 内容所对应产品的key
        Cache-Control: no-cache
        {
            "count": 1,
            "product_key": "your_product_key",
            "contents": [
                {
                    " content_id": "the_content_id_to_delete"
                }
            ]
        }
    

使用curl的示例调用


        curl -X POST -H "Content-Type: application/json" -H "Magic-Token: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIwMTE3NTQ4MzU1ZWM0ZGI5OWQwNjEzNzJmYjkzYWM0YiIsImlzX2FwaV91c2VyIjoiYXBpX3VzZXIiLCJleHAiOjE0Nzc2NzE0NTksImlhdCI6MTQ3NzY2MDY1OX0.deKp7-zHXYZlB12y_mBDyi8vusNezTDBDi1--17DBBM" -H "Account-Key: accountKey" -H "Cache-Control: no-cache"  -d '{
            "count": 1,
            "product_key": "aaa",
            "contents": [
                {
                    "content_id": "c10856862707196"
                }
            ]
        }' "http://api.mlinks.cc/api/v2/content/delete"
    

请求说明

字段 成员 类型 位置 是否必须 备注
Magic-Token string HTTP header yes
Account-Key string HTTP header yes
count number HTTP post pay load yes 该次http调用提交的删除内容数目
contents object HTTP post pay load yes
content_id string HTTP post pay load yes 需要删除的内容ID

返回说明

标准http返回

内容验证API

1、在内容推送之前,可以将内容的json进行验证,验证地址:http://c.mlinks.co/jsvalidator/

2、如果内容已经发送过来之后 还是没有在后台看到数据,那么可以参考以下地址进行查询。

示例调用


        GET //api/v2/content/validation/your_account_key HTTP/1.1
        Host: https://api.mlinks.cc
        Content-Type: application/json
        Cache-Control: no-cache
    

curl 示例调用


        curl -X GET -H "Content-Type: application/json" "https://api.mlinks.cc//api/v2/content/validation/your_account_key"
    

请求说明

字段 类型 位置 是否必须 备注
account_key string HTTP URL yes 使用前文提到的account key替换url中的your_account_key

返回说明

返回该Account Key 下最近发送的最多300条未通过验证的数据,请注意查看其中对应contentId的validationMsg,修正数据后再次发送。

【内容HTML白名单】

content内容中支持html格式,以防排列混乱,会过滤链接及外部引用的样式。转化示例及HTML白名单如下:

转换前

        <h3 class="top" style="color:red;position:fiexd;top:0;">你好</h3>
        <img src="http://mlins.cc/abc.png" />
    
转换后

        <h3 style="color:red;">你好</h3>
        <img src="http://mlins.cc/abc.png" />
    

HTML白名单

块级元素 行内元素 元素属性 css属性
div b src text_align
section br vertical_align
p em color
h1 i background
h2 img font_size
h3 span line-height
h4 strong
h5 u
h6
hr
【图文混排格式】

以下支持App方通过API方式向魔窗推送内容数据中的图文混排的格式说明。

接口中的标签使用HTML标准标签扩展,现在只支持【标签说明】中的标签。现版本暂时不支持标签的嵌套。

标签说明

标签名称 属性 说明
<m:p></m:p> 一段文字
text-indent 首行缩进和style同名属性意义一致
默认值:0
<m:img /> 一张图片
src 图片地址(需要是全路径,并且需要允许content.mlinks.co这个域名访问)
mlink 设置此属性,这个图片将被添加mLink点击事件,点击后会调用对应的mLink服务。
值必须为魔窗短链接,如果有参数,需要拼在短链接之后,如http://a.mlinks.cc/AAba?p1=abc
<m:h1></m:h1>
<m:h2></m:h2>
<m:h3></m:h3>
<m:h4></m:h4>
<m:h5></m:h5>
<m:h6></m:h6>
标题
align 取值:left|center|right
默认值:left
mlink 设置此属性,这个图片将被添加mLink事件,点击后会调用对应的mLink服务。
值必须为魔窗短链接,如果有参数,需要拼在短链接之后,如http://a.mlinks.cc/AAba?p1=abc
示例

APP方发过来的数据: 

<m:h3 mlink="http://a.mlink.cc/AAba">这是一个h3的例子</m:h3>
<m:img src="http://img.magicwindow.cn/abc1.png" />
<m:p text-indent="2em">
这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落
</m:p>
<m:img src="http://img.magicwindow.cn/abc2.png" />
<m:p>
测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二br
</m:p>

渲染后的HTML: 

<a href="http://a.mlink.cc/AAba"><h3>这是一个h3的例子</h3></a>
<img src="http://img.magicwindow.cn/abc1.png" />
<p style="text-indent: 2em"> 这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落,这是一个测试段落
</p>
<img src="http://img.magicwindow.cn/abc2.png" />
<p>
测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二测试段落二
</p>
部分字段对字符长度有限制,其中用来判断半角字符的方法如下

        public static boolean isHalfWidth(char c) {
            return '\u0000' <= c && c <= '\u00FF'
                    || '\uFF61' <= c && c <= '\uFFDC'
                    || '\uFFE8' <= c && c <= '\uFFEE';
        }