Skip to main content
Ваші користувачі підключають свої соціальні акаунти самостійно — вони автентифікуються безпосередньо в кожній мережі, і ви ніколи не бачите й не зберігаєте їхні облікові дані. Усе на цій сторінці — про те, як довести їх до цього моменту й дізнатися, чим він закінчився. Одна річ спільна для кожного маршруту: сесія зв’язування, створена за допомогою Створення Link Session з вашим API Key і Profile-Key. Нічого не підписується на вашому боці, і в процесі немає приватного ключа.

Три способи підключення

Три форми, і перші дві — це та сама інтеграція. Вибирайте для кожного потоку окремо — вони не виключають одна одну, і чимало інтеграцій використовують хостовану сторінку для онбордингу, а віджет — усередині застосунку згодом.
Два рядки з віджетом — це одна інтеграція, а не дві. Один init дає обидва варіанти: монтуйте фрейми там, де мають бути наші кнопки, і викликайте popup() з власної кнопки всюди інде. Вони ділять одну сесію і звітують через ті самі обробники.Прямий режим (Direct Mode) — це те саме спливаюче вікно, але без нашого скрипта — для сторінки із суворою Content-Security-Policy, сторінки з серверним рендерингом або нативного застосунку. Там ви відкриваєте спливаюче вікно й стежите за ним самостійно.Не впевнені? Почніть із хостованої сторінки зв’язування. Їй не потрібні Max Pack і додаткові параметри, і це найшвидший шлях до чогось працюючого — перехід на віджет пізніше не змінює спосіб створення сесій.

Створення посилання

Викличте Створення Link Session, передавши Profile-Key користувача в заголовку. Для хостованої сторінки це весь запит:
cURL
Ви отримуєте назад url із короткочасним непрозорим токеном:
Linking URL
Ви також можете перевірити, чи посилання відкривали, і відкликати його до завершення строку дії.
Це однохвилинне відео показує створення посилання. Його записали до появи сесій зв’язування, тому в ньому досі показано надсилання Private Key — цей крок більше не потрібен, а все інше в ньому не змінилося.

Надсилання URL зв’язування

URL зв’язування авторизує вашого користувача в його профілі, тож ставтеся до нього як до пароля. Надсилайте його каналом, якому довіряєте, не записуйте в логи й не передавайте третім особам. Він залишається придатним протягом усього свого вікна, тож перезавантаження або повторна спроба OAuth працюють — але надсилайте кожне посилання лише одному користувачу і створюйте окреме посилання для кожної особи.

Відкриття URL зв’язування

Відкривайте його у новій вкладці браузера, новому вікні або view controller. Ви можете керувати закриттям або перенаправленням цього вікна.
Соціальні мережі не дозволяють відкривати хостовану сторінку зв’язування всередині iFrame або приховувати схвалений партнерський origin profile.ayrshare.com. Якщо ви хочете, щоб зв’язування відбувалося всередині вашої власної сторінки, саме для цього існує вбудований віджет: його фрейми обслуговуються з origin Ayrshare і є підтримуваним способом це зробити.

Як дізнатися, що все завершено

Два сигнали, і можна використовувати будь-який:
  • Події завершення зв’язування — задайте origin під час створення посилання, і вікно зв’язування надсилатиме connect:success, connect:error і connect:cancelled на вашу сторінку в міру того, як вони відбуваються. Без опитування.
  • Отримання Link Session — повідомляє completedAt, lastCompletedAt і completedNetworks. Це сигнал для нативних застосунків і єдиний для Telegram, який завершує підключення поза основним потоком.

Строк дії посилання

Посилання дійсне 5 хвилин за замовчуванням. Після цього створіть нове. З Max Pack задайте expiresIn у хвилинах, щоб розширити це вікно — до 2880 хвилин (48 годин), що є максимумом, який приймає API:
Expires In
Саме довше вікно робить надсилання посилання електронною поштою практичним — користувач, який повторно підключає відв’язаний акаунт, може перейти з вашого листа прямо до мережі, не відвідуючи спершу ваш застосунок.
Обговоріть зі своєю командою безпеки, як довго посилання має залишатися активним. Довше вікно — це довший період, протягом якого перехоплене посилання все ще працює. Якщо посилання потрапило не в ті руки, ви можете відкликати його, а не чекати завершення строку дії.

Profile Key

Profile-Key визначає, для якого User Profile призначене посилання. Знайти його можна в панелі розробника Ayrshare, перемкнувшись на цей профіль.
Private Key більше не використовується. Посилання не підписуються, тож немає чого читати з файлу чи вставляти у ваш код. Застарілий параметр privateKey досі приймається й ігнорується, тому наявні інтеграції продовжують працювати, а файл private.key у вашому Integration Package можна не використовувати.

Перемикання профілів

Якщо профіль уже авторизований, відкриття посилання іншого профілю не перемикає профілі — це зроблено навмисно й забезпечує швидкий досвід для користувача, який уже там. Щоб примусово перемкнути профіль, див. Automatic Logout of a Profile Session. Акаунти Instagram можна прив’язати двома способами: безпосередньо через Instagram Login або через підключену Facebook Page. Який процес починається, коли користувач натискає кнопку Instagram, зазвичай контролюється налаштуванням Instagram Login на рівні акаунту. Параметр тіла instagramLinkMethod перевизначає це налаштування для окремого посилання:
Instagram Link Method
Перевизначення діє протягом усього життя цього посилання, включно з перенаправленням авторизації Instagram/Facebook. Кілька моментів, які варто знати:
  • Воно не змінює налаштування на рівні акаунту й не впливає на жодне інше посилання.
  • Якщо його пропустити, застосовується налаштування на рівні акаунту, як і раніше.
  • Недійсне значення повертає 400 зі списком допустимих значень (instagram, facebook).
  • Перегляньте відмінності функцій перед вибором — деякі функції Instagram, такі як пошук хештегів і колаборації, доступні лише за автентифікації через Facebook Page.

Connect Accounts Email

Ayrshare може надіслати посилання вашому користувачу електронною поштою за вас, щоб він міг потрапити на свою сторінку зв’язування, не відвідуючи ваш застосунок. Поєднуйте це з довшим expiresIn — стандартні п’ять хвилин рідко переживають поштову скриньку.

Connect Accounts JSON

Кожне поле всередині email обов’язкове. Відсутність будь-якого зриває надсилання.
Example Contact Email Request
expiresIn — параметр верхнього рівня, а не частина об’єкта email. Вкладений в email, він ігнорується, і ваш користувач отримує посилання, строк дії якого спливає за п’ять хвилин.
Відповідь повідомляє результат у полі emailSent:
Example Contact Email Response
Якщо email не вдалося надіслати, запит усе одно успішний і ви отримуєте посилання. Відповідь містить emailSent: false і об’єкт emailError, тож ви можете передати посилання користувачу іншим способом:
Example Failed Email Response
emailError з’являється щоразу, коли ви запитали email, але його не надіслали: або надсилання не вдалося, або в об’єкті email бракувало обов’язкового поля, і тоді details називає відсутні поля. emailSent: false без emailError означає, що email не запитували. Якщо немає to, ситуація інша: увесь запит відхиляється з code: 188.

Приклад Connect Accounts Email

Ось приклад електронного листа, що відкриває сторінку соціального зв’язування: Connect Accounts email Лист надійде з адреси: Social Connect Hub <connect@socialconnecthub.com>

Мобільні застосунки

Відкривайте URL зв’язування в системному браузері, ніколи не у вбудованому webview: Google відхиляє вхід у ньому з disallowed_useragent, а Meta блокує його повністю. Ваш користувач побачить власну сторінку помилки мережі, і ніщо на вашому боці цього не виправить.
  • iOS — ASWebAuthenticationSession або SFSafariViewController.
  • Android — Chrome Custom Tabs.
Оскільки нативний застосунок не має вікна браузера, куди можна надсилати події, отримуйте результат натомість із Отримання Link Session. Задайте origin як вашу власну схему (myapp://connected), щоб сторінка мала шлях назад у ваш застосунок.

Приклади мобільного коду

Замініть linkingURL на url, повернений із Створення Link Session.

Тестування

Рекомендується спочатку створити посилання в Postman. Ваш Integration Package — на сторінці API Key основного профілю (Primary Profile) в панелі керування — містить зразкову конфігурацію Postman. Імпортуйте її, заповніть свій Profile Key у полі body profileKey і натисніть Send. Зразкова конфігурація досі заповнює privateKey і domain. privateKey ігнорується, а domain можна очистити, якщо ваш акаунт не має більше ніж одного домену зв’язування. Ви також можете згенерувати код із Postman.

Bubble.io

Bubble linking URL

Legacy: generateJWT

Генерація URL для підключення (generateJWT) виконує ту саму роботу і є застарілою — повністю підтримується, не має дати вилучення і працює без змін для посилань, які ви вже роздали. Її власна сторінка документує параметри, включно з трьома, які тепер приймаються й ігноруються.Обидва ендпоінти використовують той самий валідатор, тож усе на цій сторінці стосується будь-якого з них. Одна відмінність, яку варто знати під час міграції: generateJWT терпить три речі, які Створення Link Session відхиляє — нерозпізнану мережу в allowedSocial, лише одну половину облікових даних X і нерядковий redirect.