Новый формат загрузки креативов

Загрузка креативов

Единый интерфейс загрузки креативов:

POST /api/v2/content/(static|video|html5).json

static.json – используется для загрузки картинок (POST /api/v2/content/static.json)

video.json – используется для загрузки видео (POST /api/v2/content/video.json)

html5.json – используется для загрузки html5-креативов (POST /api/v2/content/html5.json)

Запрос должен иметь тип multipart/form-data.

Пример запроса:

curl -X POST -H "Authorization: Bearer LIDM…Io4Qj"  -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -F "file=@[object Object]" -F "data={"width":1612, "height":980}" "https://target.my.com/api/v2/content/static.json

Width и height – обязательные параметры для static.json и video.json. Необходимо указать исходную ширину и высоту контента.

Для html5-формата достаточно указать файл, соответствующий https://sales.mail.ru/ru/russia/main/latest/technical/#a75.

Пример ответа:

{
  "variants": {
    "original": {
      "url": "https://r.mradx.net/img/A2/B0D399.jpg",
      "width": 1612,
      "size": 237619,
      "height": 980
    }
  },
  "id": 6666
}

  • Id – идентификатор креатива
  • Variants – список доступных форматов креатива. При первой загрузке будет содержать только оригинальные характеристики исходного креатива (широта, высота, размер и адрес). Для html5-формата variants всегда содержит только original, без указания высоты и ширины. 

Возможные ошибки

Все ошибки имеют вид:

{
    "error": {
        "code": "validation_failed",
        "fields": {
            "file": <ошибка>
        },
        "message": "Validation failed"
    }
}

Возможные ошибки для static.json и video.json:

  • {"code": "format_not_supported", "message": "Unsupported content format"}
  • {"code": "cannot_upload", "message": "Cannot upload content"}
  • {"code": "no_file", "message": "Content not found in the request. Request must have multipart/form-data type with "file" field."}
  • {"code": "broken_content", "message": "Content is broken"}
  • {"code": "content_too_large", "message": "Content is too large"}
  • {"code": "content_bad_size", "message": "Content has bad size"}

Возможные коды ошибок для html5.json:

  • bad_archive
  • no_html_file
  • too_many_html_files
  • invalid_file_name
  • validation_error

Подробности ошибок описаны в поле message.

Изменения в объекте banner

В объект баннера добавляется поле content, описывающее соответствующий баннеру креатив в новом формате.

При чтении баннеров будет возвращаться структура вида:

    {
     ...
    "content": {
        "primary_image": {
            "id": 123,
            "type": "static",
            "variants": {
                "original":
                    "url": "http://asdasdas.net/asdasd1",
                    "width": 200,
                    "height": 400,
                    "size": 1234567
                },
                "100x200": {
                    "url": "http://asdasdas.net/asdasd2",
                    "width": 100,
                    "height": 200,
                    "size": 123456,
                    "is_animated": true
                }
            }
        },
        "promo_image": {
            "id": 100500,
            "type": "static",
            "variants": {
                "original": {
                    "url": "http://url.to/video",
                    "size": 100500100500,
                    "height": 400,
                    "width": 240
                }
            }
        }
        "primary_video": {
            "id": 100500,
           "type": "video",
            "variants": {
                "original": {
                    "url": "http://url.to/video",
                    "size": 100500100500,
                    "height": 400,
                    "width": 240
                }
            }
        }
    },
    ...
}

Content содержит список креативов различного назначения. В данном примере primary_image, promo_image и primary_video – это различные креативы, используемые в разных частях готового баннера. Необходимые баннеру типы креативов описаны в структуре banner_format пакета.

В каждом из описаний креатива помимо идентификатора и типа креатива указываются имеющиеся варианты креатива. По большей части они несут исключительно служебную функцию, но вы можете увидеть по ссылке, как будет выглядеть креатив в готовом баннере.

При создании/изменении баннеров вместо image используется поле content. Нужно указать все перечисленные в banner_format типы креативов со ссылкой на идентификатор уже загруженного с помощью content/static|video.json контента.

    ...
    "content": {
        "primary_image": {
            "id": 123
        },
        "promo_image": {
            "id": 456
        },
        "primary_video": {
            "id": 900
        }
    },
    ...

Обратите внимание, что id, возвращенные при загрузке через images.json здесь использовать некорректно.

Для удаления того или иного элемента, необходимо явно указать удаление. К примеру:

    ...
    "content": {
        "primary_image": null
    },
    ...

Баннерный формат

Необходимые для создания баннера типы креативов описаны в баннерном формате пакета (GET /api/v2/packages.json).

Для пакетов, использующих новый тип контента, в fields_ баннерного формата будет указан объект content, в котором будут представлены необходимые типы креативов для данного пакета. Ранее, типы креативов указывались непосредственно в fields_.

Поле type в описании креатива подскажет с помощью какого метода необходимо грузить контент – video или static. Required определяет обязательность данного креатива в баннере, а в variants перечислены подходящие размеры креативов.

Например, следующий формат требует при создании баннера content типа image и promo_image:

...
"banner_format": {
    ...,
    "fields_": {
        ...,
        "content": {
            "image": {
                "type": "static",
                "read_only": false,
                "required": true,
                "variants": {
                    "50x50": {
                        "width": 50,
                        "height": 50
                    }
                },
                ...
            },
            "promo_image": {
                "type": "static",
                "required": true,
                "read_only": false,
                "variants": {
                    "150x84": {
                        "fixed_size": true,
                        "width": 150,
                        "height": 84
                    },
                    "480x270": {
                        "fixed_size": false,
                        "width": 480,
                        "height": 270
                    }
                },
                ...
            },
        },
        ...
    },
    ...
},
...