Кнопка «Поделиться»

Кнопка публикует ссылку на вашу страницу на стене пользователя Апельсинки и в ленте его друзей. К записи автоматически подтягивается превью: заголовок, описание и картинка из тегов og:title, og:description, og:image (или <title>, <meta name="description"> и самая крупная картинка на странице — не меньше 120×120).

Собрать кнопку в конструкторе

Зачем сайту эта кнопка: круг соцтрафика

Каждое нажатие — это запись со ссылкой и превью в ленте читателя. Её видят его друзья, часть из них приходит к вам — и уже они делятся дальше. Трафик идёт по кругу, а не один раз:

Сколько это даёт, зависит от трёх чисел: какая доля читателей нажимает кнопку, сколько у них друзей и какая доля друзей переходит по записи. Их произведение k — сколько новых читателей приводит один читатель за круг. Пример (числа условные, для иллюстрации):

Здесь k = 0,03 × 120 × 0,04 = 0,144: тысяча читателей приводит ещё около 168 (+17%), дальше круги затухают. Самый сильный рычаг — доля нажавших: если она вырастает с 3% до 6% (публикация в один клик, понятная надпись, кнопка рядом с материалом), k удваивается до 0,288, и те же 1000 читателей приводят уже около 395 новых. Если k больше 1, каждый следующий круг больше предыдущего и трафик растёт сам; обычно k меньше 1, и кнопка даёт прибавку к каждому посещению — бесплатно.

Установка

<script type="text/javascript" src="//api.apelsinki.com/widgets/share.js"></script>
<div class="sv-share" data-url="https://example.com/article"></div>

Скрипт достаточно подключить один раз на странице; кнопок может быть сколько угодно. Кнопки, добавленные скриптом позже, инициализируются вызовом SV.Share.init(). Адрес скрипта начинается с // — он загрузится по тому же протоколу, что и ваша страница (http или https).

Как публикуется. В современных браузерах кнопка показывается во фрейме Апельсинки: если посетитель уже вошёл на сайт, публикация происходит в один клик, без окна. Иначе открывается окно входа и подтверждения. В старых браузерах (IE 5.5–9, Opera 9, Firefox до 3.5) — та же кнопка прямо на странице и окно публикации.

Параметры

Все атрибуты необязательны. Без них кнопка выглядит как раньше — уже установленные кнопки не меняются.

Как считается счётчик

Счётчик — число профилей, которые поделились этим адресом, любым способом. Один профиль засчитывается один раз, сколько бы записей он ни сделал. Адрес нормализуется: http/https, www., метки utm_* и # не различаются. Если задан data-count, показывается ваше число; после публикации оно растёт на 1, пока вы не поставите своё через SV.Share.setCount().

Состояния кнопки

1. Обычное — надпись и счётчик.
2. Загрузка — после нажатия, пока идёт публикация или открыто окно, на кнопке анимация.
3. Поделились — «Вы поделились» (для голосования «Вы проголосовали»), неактивна. Кнопка сама узнаёт это состояние при загрузке страницы, если пользователь уже делился этим адресом через кнопку.

Через кнопку профиль может поделиться адресом один раз. Поделиться повторно можно через окно по прямой ссылке (см. ниже) — это не меняет счётчик.

События

SV.Share.on('share', function (d) {
  // публикация состоялась (не просто нажатие):
  // d.url, d.count — новый счётчик, d.element — div кнопки,
  // d.action — 'share' | 'vote', d.mode — 'oneclick' | 'popup' | 'poll',
  // d.receipt — подпись для проверки на вашем сервере
});
SV.Share.on('state', function (d) {
  // состояние при загрузке страницы: d.shared == 1 — посетитель уже делился,
  // d.receipt — подпись (событие 'share' в этом случае не приходит)
});

В старых браузерах события тоже работают: кнопка опрашивает сервер, пока открыто окно публикации (d.mode == 'poll').

Проверка подписи: голосование через Апельсинки

d.receipt доказывает, что этот профиль Апельсинки поделился этим адресом через кнопку на вашем сайте. Отправьте его на свой сервер (например, вместе с голосом) и проверьте ключом сайта. Подпись имеет вид P.SIG: P — данные в base64url (JSON {"v":1,"s":домен,"u":адрес,"p":профиль,"t":время,"a":"share"|"vote"}), SIG — первые 32 символа HMAC-SHA256 от P.

<?php
// $key — ключ вашего сайта, $domain — ваш домен без www, например 'example.com'
function apelsinki_receipt($receipt, $url, $key, $domain)
{
    $x = explode('.', (string)$receipt);
    if (count($x) != 2) return false;
    if (!hash_equals(substr(hash_hmac('sha256', $x[0], $key), 0, 32), $x[1])) return false;
    $d = json_decode(base64_decode(strtr($x[0], '-_', '+/')), true);
    if (!is_array($d) || $d['s'] !== $domain || $d['u'] !== $url) return false;
    if ($d['t'] < time() - 86400) return false;   // подпись старше суток
    return $d;   // $d['p'] — постоянный id профиля для вашего сайта, $d['a'] — share | vote
}
// один голос на материал и профиль: уникальный ключ (item_id, puid)
// INSERT IGNORE INTO votes (item_id, puid) VALUES (?, ?)

u — адрес ровно как в data-url, поэтому для голосований задавайте data-url явно. p — постоянный псевдоним профиля: у одного человека на вашем сайте он всегда один и тот же, на других сайтах — другой. Ключ сайта (32 символа) выдаёт администрация Апельсинки для вашего домена — напишите через Помощь. Ключ храните только на сервере, в страницу не выводите.

Другие вызовы

Прямая ссылка на окно «Поделиться» и готовый комментарий

Окно публикации можно открыть без кнопки: http://api.apelsinki.com/share?url=АДРЕС (окно 520×460). Параметр comment=ТЕКСТ заранее заполняет поле комментария — пользователь видит текст, может изменить и нажимает «Поделиться»:

<a href="http://api.apelsinki.com/share?url=https://example.com/vote/123&comment=Голосую+за+Машу!+Поддержите+и+вы"
   onclick="window.open(this.href, 'sv_share', 'width=520,height=460'); return false;">Поделиться с друзьями</a>

Что происходит после нажатия: на страницу пользователя добавляется запись со ссылкой (в ленту друзей), а текст комментария публикуется первым комментарием под этой записью. У всех друзей пользователя это появляется в разделе «Обсуждения» с непрочитанным ответом — счётчик в шапке загорается, друг видит «Игорь обсуждает: Голосую за Машу!» и может ответить. Так одна ссылка даёт и охват в ленте, и живое обсуждение.

Правила те же: по прямой ссылке делиться можно сколько угодно раз, счётчик кнопки считает профили один раз. Текст комментария — до 1000 символов, HTML не допускается.

Серверный счётчик

Счётчик с сервера: GET http://api.apelsinki.com/widgets/share/count?url=АДРЕС => {"url":"…","count":12}.

Совместимость

Кнопка работает в Internet Explorer 5.5 и новее, Opera 9, Firefox 1.5 и во всех современных браузерах. Внешних библиотек не требует, ничего не пишет в cookies вашего сайта.

Собрать кнопку в конструкторе