API блока «Поделиться»

Если ваш сайт реализован в виде одностраничного приложения, вы можете встроить блок на любом DOM-элементе сайта с помощью API блока «Поделиться».

  1. Подключите скрипт блока. Если требуется поддержка старых браузеров (например, Internet Explorer 8), дополнительно подключите скрипт es5-shims. Этот скрипт должен быть подключен перед скриптом блока:

    <script src="https://yastatic.net/es5-shims/0.0.2/es5-shims.min.js"></script>
    <script src="https://yastatic.net/share2/share.js"></script>
  2. Вызовите метод Ya.share2. Передайте методу идентификатор элемента и объект параметров.

    Метод Ya.share2 возвращает экземпляр блока «Поделиться». Если вы сохраните экземпляр блока в переменную, то сможете использовать методы экземпляра блока.

    var share = Ya.share2('my-share', {
        content: {
            url: 'https://yandex.com'              
        }
        // здесь вы можете указать и другие параметры
    });

    Также вместо идентификатора вы можете передать сам элемент:

    var myShare = document.getElementById('my-share');
    
    var share = Ya.share2(myShare, {
        content: {
            url: 'https://yandex.com'      
        }
       // здесь вы можете указать и другие параметры
    });

Внутри объекта параметры объединяются в группы:

  • content — параметры контента, которым нужно поделиться;
  • contentByService — параметры контента для каждого сервиса отдельно;
  • theme — параметры внешнего вида блока;
  • hooks — функции, которые нужно вызвать при наступлении одного из событий блока.

content

Внутри группы content можно указать параметры контента, которым нужно поделиться: адрес и заголовок страницы, ссылку на изображение, текст описания.

Ya.share2('my-share', {
    content: {
        url: 'https://yandex.com',
        title: 'Yandex',
        description: 'All about Yandex',
        image: 'https://yastatic.net/morda-logo/i/logo.svg'   
    }
});
Поддерживаемые параметры
Параметр Описание Возможные значения
description Текст, которым нужно поделиться. Строка.
image Изображение, которым нужно поделиться. URL изображения.
title Заголовок, которым нужно поделиться. Строка.

По умолчанию указывается заголовок страницы, на которой размещен блок.

url Ссылка, которой нужно поделиться. Любой URL.

По умолчанию указывается URL страницы, на которой размещен блок.

Параметр Описание Возможные значения
description Текст, которым нужно поделиться. Строка.
image Изображение, которым нужно поделиться. URL изображения.
title Заголовок, которым нужно поделиться. Строка.

По умолчанию указывается заголовок страницы, на которой размещен блок.

url Ссылка, которой нужно поделиться. Любой URL.

По умолчанию указывается URL страницы, на которой размещен блок.

Некоторые соцсети могут обрабатывать большие строки некорректно. Вы можете сразу указывать значения параметров контента с учетом этого или указать значения для таких соцсетей отдельно.

Примечание. Часто соцсети игнорируют параметры title и description и берут значения из семантической разметки страницы. О том, как использовать семантическую разметку, читайте в статьях Open Graph, Schema.org и Микроформаты.

contentByService

Внутри группы contentByService можно указать параметры контента для каждой соцсети отдельно. Например, это может понадобиться для Твиттера, где установлено ограничение на длину сообщения.

Также для Твиттера можно указать хэштеги. Несколько хэштегов указываются через запятую, без пробела и знака #.

Ya.share2('my-share', {
    content: {
        url: 'https://yandex.com',
        title: 'Yandex'
    },

    contentByService: {
        twitter: {
            url: 'https://ya.ru',
            title: 'Яндекс',
            hashtags: 'yandex,share'
        }
    }
});

Facebook ограничивает количество публикаций в минуту. Чтобы снять ограничение, укажите токен. Подробнее о токенах Facebook см. в статье Маркеры доступа.

Ya.share2('my-share', {
    content: {
        url: 'https://yandex.com',
        title: 'Yandex'
    },

    contentByService: {
        facebook: {
            url: 'https://ya.ru',
            title: 'Яндекс',
            accessToken: 'fb-token'
        }
    }
});

theme

Внутри группы theme можно указать параметры, относящиеся к внешнему виду блока:

Ya.share2('my-share', {
    theme: {
        services: 'messenger,facebook,lj,viber,twitter',
        lang: 'uk',
        limit: 3,
        size: 's',
        bare: false
    }
});
Поддерживаемые параметры
Параметр Описание Возможные значения
bare Признак того, что загрузка стилей отключена. Если добавить параметр, соцсети будут отображаться в виде текстового вертикального списка.
  • true — стили не подгружаются;
  • false — стили подгружаются.

Значение по умолчанию: false

colorScheme Цветовая схема кнопок соцсетей.
  • blackwhite — белые иконки на черном фоне
  • whiteblack — черные иконки на белом фоне
  • normal — белые иконки на индивидуальном фоне

Значение по умолчанию: normal.

copy Позиция кнопки Скопировать ссылку. Кнопка может отображаться в pop-up по нажатию , если используется атрибут limit, или в основном списке соцсетей.
  • first — кнопка вверху списка в pop-up;
  • last — кнопка внизу списка в pop-up;
  • hidden — кнопка не отображается в pop-up;
  • extraItem — кнопка в основном списке.

Значение по умолчанию: last.

curtain

Указание на мобильных устройствах вместо pop-up выводить окно, похожее на нативный инструмент Поделиться.

В шапке окна отображается превью сайта.

Источники данных для превью
Контент в превью может не совпадать с контентом для соцсети. Картинка и описание для превью берутся из атрибутов image и description. Если атрибуты image и description не указаны, данные подтягиваются из разметки Open Graph. Если описание не найдено в разметке Open Graph, оно подставляется из мета-тега description страницы. Если описания нет и там, берется текущий URL страницы.

Кнопка Другие для вызова нативного инструмента Поделиться и кнопка Скопировать ссылку присутствуют в окне, если такая возможность предусмотрена браузером.

  • true — заменять стандартный pop-up;
  • false — не заменять стандартный pop-up.

Значение по умолчанию: false

direction Направление списка кнопок.
  • horizontal — горизонтальное;
  • vertical — вертикальное.

Значение по умолчанию: horizontal.

lang Язык блока. Локализуются подписи кнопок соцсетей и кнопка Скопировать ссылку.
  • az — азербайджанский;
  • be — белорусский;
  • en — английский;
  • hy — армянский;
  • ka — грузинский;
  • kk — казахский;
  • ro — румынский;
  • ru — русский;
  • tr — турецкий;
  • tt — татарский;
  • uk — украинский;
  • uz — узбекский.

Значение по умолчанию: ru.

limit Количество соцсетей, отображаемых в виде кнопок. Используется если нужно встроить в блок много соцсетей, а также чтобы блок занимал мало места на странице. Не вошедшие в лимит соцсети будут отображаться в pop-up по нажатию кнопки . Натуральное число или отсутствие свойства.
moreButtonType Вид кнопки открытия pop-up, если значение limit равно 0.
  • long — с надписью
  • short — без надписи
  • значение не задано — стандартный вид
nonce Идентификатор директивы Content Security Policy. Используется для подтверждения безопасности скрипта блока «Поделиться». Строка, сгенерированная сервером.
popupDirection Направление открытия pop-up.
  • bottom — вниз;
  • top — вверх;
  • auto — по умолчанию вниз; если не вмещается вниз, то вверх; если не вмещается ни вниз, ни вверх, то вниз.

Значение по умолчанию: bottom.

popupPosition Расположение pop-up относительно контейнера блока. Значение outer может понадобиться в том случае, если из-за специфики верстки вашего сайта pop-up обрезается соседними элементами страницы.
  • inner — внутри контейнера;
  • outer — снаружи контейнера.

Значение по умолчанию: inner.

services Список идентификаторов социальных сетей, отображаемых в блоке. См. список идентификаторов поддерживаемых соцсетей. Несколько соцсетей указываются через запятую без пробела.

Значение по умолчанию: collections,vkontakte,facebook,twitter

shape Форма кнопок соцсетей.
  • round — круглая
  • normal — прямоугольная со скругленными углами

Значение по умолчанию: normal.

size Размер кнопок соцсетей.
  • l — большой
  • m — средний
  • s — маленький

Значение по умолчанию: m.

useLinks Указание, что страницу отправки ссылки нужно всегда открывать в новом окне или вкладке. Если атрибут не добавлять, страница может выводиться во всплывающем окне (возможность зависит от соцсети и браузера).
  • true — открывать новую вкладку или окно;
  • false — открывать всплывающее окно.

Значение по умолчанию: false

Параметр Описание Возможные значения
bare Признак того, что загрузка стилей отключена. Если добавить параметр, соцсети будут отображаться в виде текстового вертикального списка.
  • true — стили не подгружаются;
  • false — стили подгружаются.

Значение по умолчанию: false

colorScheme Цветовая схема кнопок соцсетей.
  • blackwhite — белые иконки на черном фоне
  • whiteblack — черные иконки на белом фоне
  • normal — белые иконки на индивидуальном фоне

Значение по умолчанию: normal.

copy Позиция кнопки Скопировать ссылку. Кнопка может отображаться в pop-up по нажатию , если используется атрибут limit, или в основном списке соцсетей.
  • first — кнопка вверху списка в pop-up;
  • last — кнопка внизу списка в pop-up;
  • hidden — кнопка не отображается в pop-up;
  • extraItem — кнопка в основном списке.

Значение по умолчанию: last.

curtain

Указание на мобильных устройствах вместо pop-up выводить окно, похожее на нативный инструмент Поделиться.

В шапке окна отображается превью сайта.

Источники данных для превью
Контент в превью может не совпадать с контентом для соцсети. Картинка и описание для превью берутся из атрибутов image и description. Если атрибуты image и description не указаны, данные подтягиваются из разметки Open Graph. Если описание не найдено в разметке Open Graph, оно подставляется из мета-тега description страницы. Если описания нет и там, берется текущий URL страницы.

Кнопка Другие для вызова нативного инструмента Поделиться и кнопка Скопировать ссылку присутствуют в окне, если такая возможность предусмотрена браузером.

  • true — заменять стандартный pop-up;
  • false — не заменять стандартный pop-up.

Значение по умолчанию: false

direction Направление списка кнопок.
  • horizontal — горизонтальное;
  • vertical — вертикальное.

Значение по умолчанию: horizontal.

lang Язык блока. Локализуются подписи кнопок соцсетей и кнопка Скопировать ссылку.
  • az — азербайджанский;
  • be — белорусский;
  • en — английский;
  • hy — армянский;
  • ka — грузинский;
  • kk — казахский;
  • ro — румынский;
  • ru — русский;
  • tr — турецкий;
  • tt — татарский;
  • uk — украинский;
  • uz — узбекский.

Значение по умолчанию: ru.

limit Количество соцсетей, отображаемых в виде кнопок. Используется если нужно встроить в блок много соцсетей, а также чтобы блок занимал мало места на странице. Не вошедшие в лимит соцсети будут отображаться в pop-up по нажатию кнопки . Натуральное число или отсутствие свойства.
moreButtonType Вид кнопки открытия pop-up, если значение limit равно 0.
  • long — с надписью
  • short — без надписи
  • значение не задано — стандартный вид
nonce Идентификатор директивы Content Security Policy. Используется для подтверждения безопасности скрипта блока «Поделиться». Строка, сгенерированная сервером.
popupDirection Направление открытия pop-up.
  • bottom — вниз;
  • top — вверх;
  • auto — по умолчанию вниз; если не вмещается вниз, то вверх; если не вмещается ни вниз, ни вверх, то вниз.

Значение по умолчанию: bottom.

popupPosition Расположение pop-up относительно контейнера блока. Значение outer может понадобиться в том случае, если из-за специфики верстки вашего сайта pop-up обрезается соседними элементами страницы.
  • inner — внутри контейнера;
  • outer — снаружи контейнера.

Значение по умолчанию: inner.

services Список идентификаторов социальных сетей, отображаемых в блоке. См. список идентификаторов поддерживаемых соцсетей. Несколько соцсетей указываются через запятую без пробела.

Значение по умолчанию: collections,vkontakte,facebook,twitter

shape Форма кнопок соцсетей.
  • round — круглая
  • normal — прямоугольная со скругленными углами

Значение по умолчанию: normal.

size Размер кнопок соцсетей.
  • l — большой
  • m — средний
  • s — маленький

Значение по умолчанию: m.

useLinks Указание, что страницу отправки ссылки нужно всегда открывать в новом окне или вкладке. Если атрибут не добавлять, страница может выводиться во всплывающем окне (возможность зависит от соцсети и браузера).
  • true — открывать новую вкладку или окно;
  • false — открывать всплывающее окно.

Значение по умолчанию: false

hooks

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

Ya.share2('my-share', {
    hooks: {
        onready: function () {
            alert('блок инициализирован');
        },

        onshare: function (name) {
            alert('нажата кнопка' + name);
        }
    }
});
Поддерживаемые события
Событие Описание Аргументы
onready Срабатывает при инициализации блока.
onshare Срабатывает при нажатии на кнопку соцсети. name — название соцсети.
Событие Описание Аргументы
onready Срабатывает при инициализации блока.
onshare Срабатывает при нажатии на кнопку соцсети. name — название соцсети.

Методы

Метод Ya.share2 возвращает экземпляр блока «Поделиться». Для каждого экземпляра блока доступны методы:

  • updateContent — обновляет контент для всех сервисов;
  • updateContentByService — обновляет контент для отдельного сервиса;
  • destroy — очищает контейнер блока и удаляет все обработчики событий.

Вы можете вызвать эти методы, сохранив экземпляр блока в переменную. Если вы не сохранили экземпляр блока в переменную, вы можете вызвать методы внутри группы параметров hooks.

updateContent

Метод позволяет переопределить параметры контента после инициализации блока. Формат аргументов метода совпадает с форматом параметров группы content.

Чтобы вызвать метод для конкретного экземпляра блока, сохраните этот экземпляр в переменную.

var share = Ya.share2('my-share', {
    content: {
        url: 'https://yandex.com'              
    }
    // здесь вы можете указать и другие параметры
});

share.updateContent({
    title: 'Shiny share button',
    description: 'To rule them all',
    url: 'https://tech.yandex.ru/share/'
});
updateContentByService

Метод позволяет переопределить параметры контента для отдельного сервиса после инициализации блока. Формат аргументов метода совпадает с форматом параметров группы contentByService.

Чтобы вызвать метод для конкретного экземпляра блока, сохраните этот экземпляр в переменную.

var share = Ya.share2('my-share', {
    content: {
        url: 'https://yandex.com'              
    }
    // здесь вы можете указать и другие параметры
});

share.updateContentByService({
    twitter: {
        title: 'Easy to share',
        url: 'https://tech.yandex.ru/share/'
    }
});
destroy

Метод позволяет очистить контейнер блока и удалить все обработчики событий.

Чтобы вызвать метод для конкретного экземпляра блока, сохраните этот экземпляр в переменную.

var share = Ya.share2('my-share', {
    content: {
        url: 'https://yandex.com'              
    }
    // здесь вы можете указать и другие параметры
});

share.destroy();