Практичний посібник з інтеграції Facebook OAuth 2.0
Часта проблема при інтеграції Facebook OAuth — callback повертає помилку або email виявляється null. Access token може закінчитися, якщо не налаштоване оновлення. За статистикою, до 30% користувачів віддають перевагу входу через соцмережі, тому помилки тут критичні. Ми такі сценарії опрацьовуємо на етапі інтеграції — маємо 5+ років досвіду та 50+ виконаних проєктів з авторизацією через соцмережі, накопичили типові рішення.
Офіційна документація Facebook Login рекомендує використовувати OAuth 2.0 з redirect-флоу. На практиці інтеграція через Laravel Socialite скорочує час розробки в 3 рази порівняно з ручною реалізацією на cURL, що економить до 35% бюджету проєкту (вартість базової інтеграції — від $500). Нижче розберемо повний цикл: від створення додатку в Meta до Data Deletion Callback — з робочим кодом на Laravel Socialite та альтернативою через JS SDK.
Створення додатку в Meta Developer Console
- Відкрийте developers.facebook.com → My Apps → Create App.
- Виберіть тип Consumer (для публічного входу).
- Додайте продукт Facebook Login → Web.
- У налаштуваннях Facebook Login вкажіть Valid OAuth Redirect URIs — це ендпоінт, куди Facebook буде перенаправляти користувача після авторизації. У режимі розробки додаток доступний лише тестовим користувачам. Для публічного доступу необхідно пройти App Review — процедура займає від 1 до 5 робочих днів.
- Зафіксуйте App ID та App Secret — вони знадобляться в конфігурації.
Як працює OAuth 2.0 потік через Laravel Socialite?
Важливо: соціальний вхід через Socialite в 3 рази швидше та простіше, ніж реалізація з нуля. Налаштування займає 2-3 години за наявності готового шаблону.
Конфігурація та контролер:
// config/services.php
'facebook' => [
'client_id' => env('FACEBOOK_APP_ID'),
'client_secret' => env('FACEBOOK_APP_SECRET'),
'redirect' => env('FACEBOOK_REDIRECT_URI'),
];
// FacebookAuthController.php
class FacebookAuthController extends Controller
{
public function redirect(): RedirectResponse
{
return Socialite::driver('facebook')
->scopes(['email', 'public_profile'])
->redirect();
}
public function callback(): RedirectResponse
{
try {
$fbUser = Socialite::driver('facebook')->user();
} catch (\Exception $e) {
return redirect('/login')->withErrors(['facebook' => 'Помилка авторизації']);
}
// email може бути відсутнім, якщо користувач зареєстрований за телефоном
if (!$fbUser->getEmail()) {
session(['pending_facebook_id' => $fbUser->getId()]);
return redirect('/auth/complete-profile');
}
$user = User::updateOrCreate(
['facebook_id' => $fbUser->getId()],
[
'name' => $fbUser->getName(),
'email' => $fbUser->getEmail(),
'email_verified_at' => now(),
'avatar' => $fbUser->getAvatar(),
]
);
Auth::login($user, remember: true);
return redirect()->intended('/dashboard');
}
}
Чому обробка відсутнього email критична?
Facebook не гарантує повернення email: якщо користувач реєструвався за номером телефону, поле getEmail() поверне null. Без обробки цього сценарію користувач не зможе завершити реєстрацію. Рішення — зберегти Facebook ID в сесії та перенаправити на форму введення email. Після підтвердження створюємо акаунт і прив'язуємо до соцмережі. Це стандартна практика, реалізована за 1-2 години.
Складності Facebook OAuth
Аватар — Facebook повертає тимчасове посилання. Ми завантажуємо та зберігаємо зображення локально при першому вході, щоб уникнути битих посилань після зміни аватара. У 10% випадків аватар може бути відсутнім — тоді використовуємо заглушку.
App Review — для отримання email достатньо стандартного дозволу email. Якщо потрібно більше даних (друзі, пости), потрібне проходження модерації Meta. Ми допомагаємо підготувати документацію за 1-2 дні.
Коли потрібен JavaScript SDK?
Redirect-флоу через Socialite закриває 90% сценаріїв. JS SDK стане в нагоді, якщо потрібне кастомне вікно входу, автоматичний вхід для вже залогінених користувачів Facebook або інтеграція з іншими Facebook-продуктами. Порівняємо підходи:
| Критерій | Redirect-флоу (Socialite) | JS SDK |
|---|---|---|
| Час реалізації | 2-3 години | 4-6 годин |
| Безпека токена | Завжди на стороні сервера | Токен клієнта + верифікація |
| Кастомізація вікна входу | Стандартний редирект | Повний контроль UI |
| Автоматичний вхід | Не підтримується | Підтримується |
Приклад реалізації JS SDK:
<script>
window.fbAsyncInit = function() {
FB.init({ appId: '{{ config("services.facebook.client_id") }}', version: 'v19.0' });
};
</script>
<script async defer src="https://connect.facebook.net/ru_RU/sdk.js"></script>
<button onclick="fbLogin()">Увійти через Facebook</button>
<script>
function fbLogin() {
FB.login(function(response) {
if (response.authResponse) {
fetch('/auth/facebook/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrfToken },
body: JSON.stringify({ access_token: response.authResponse.accessToken }),
}).then(r => r.json()).then(data => {
window.location.href = data.redirect;
});
}
}, { scope: 'email,public_profile' });
}
</script>
На сервері верифікуємо токен через Graph API:
public function handleToken(Request $request): JsonResponse
{
$response = Http::get('https://graph.facebook.com/me', [
'access_token' => $request->access_token,
'fields' => 'id,name,email,picture',
]);
if ($response->failed()) {
return response()->json(['error' => 'Invalid token'], 401);
}
$fbData = $response->json();
$user = User::updateOrCreate(
['facebook_id' => $fbData['id']],
['name' => $fbData['name'], 'email' => $fbData['email'] ?? null]
);
Auth::login($user);
return response()->json(['redirect' => '/dashboard']);
}
Як реалізувати Data Deletion Callback?
Meta потребує endpoint для видалення даних. Створюємо маршрут з HMAC-перевіркою:
Route::post('/auth/facebook/data-deletion', function (Request $request) {
// Підтвердити підпис запиту через HMAC-SHA256
// Видалити або анонімізувати дані користувача
return response()->json([
'url' => 'https://example.com/deletion-status?id=' . $confirmationCode,
'confirmation_code' => $confirmationCode,
]);
});
Типові помилки при інтеграції: невірно вказаний Redirect URI (Facebook повертає redirect_uri_mismatch), відсутність обробки null email, закінчення токена без механізму оновлення. Всі ці сценарії ми опрацьовуємо на етапі тестування — перевіряємо успішний вхід, помилки, відкликання прав.
Що входить в роботу?
Пропонуємо налаштування Facebook OAuth під ключ за 2-3 дні. Вартість — від $500. У вартість входить:
| Етап | Деталі |
|---|---|
| Підготовка | Створення додатку Meta, налаштування Redirect URIs |
| Розробка | Інтеграція Socialite або JS SDK, обробка відсутнього email |
| Тестування | Перевірка всіх сценаріїв: успішний вхід, помилки, відкликання прав |
| Документація | Опис потоків, інструкція для App Review |
| Підтримка | Гарантія 1 місяць: виправлення багів, консультації |
Строки та гарантії
Базова інтеграція через Socialite — 1–2 робочі дні. З JS SDK, обробкою відсутнього email, Data Deletion Callback та локальним збереженням аватара — до 3 днів. На всі роботи даємо гарантію 1 місяць. Пишіть для безкоштовної оцінки вашого проєкту — допоможемо обрати оптимальний спосіб інтеграції та уникнути типових помилок. Замовте налаштування OAuth і отримайте стабільний вхід для ваших користувачів.
Детальніше в офіційній документації Facebook Login.