본문으로 건너뛰기
Unveilydocs

소셜 로그인 Bridge

네이티브 소셜 로그인 Bridge (Google, Apple, Kakao, Naver, Line, Meta)

개요

unveilyBridge.auth 네임스페이스를 사용하면 웹 페이지에서 네이티브 소셜 로그인 창을 열고 결과를 받을 수 있습니다. 소셜 로그인 SDK 설정은 소셜 로그인 설정 문서를 참고하세요.

지원 프로바이더: google, apple, kakao, naver, line, meta

플랜별 최소 요구 사항

프로바이더최소 플랜BasicStandardPro
GoogleBasic
AppleBasic
KakaoStandard
NaverStandard
LineStandard
Meta (Facebook)Pro

Google과 Apple은 Basic 플랜부터 사용할 수 있습니다. Kakao / Naver / Line은 Standard, Meta는 Pro가 필요합니다.


준비 상태 — unveilyGlueReady

window.unveilyBridge는 페이지 로드 전에 등록되지만, auth 네임스페이스는 글루 스크립트가 주입된 이후에 사용할 수 있습니다. SPA에서 마운트 시점에 auth.*를 호출하는 경우 unveilyGlueReady 이벤트를 먼저 기다리세요. 버튼 클릭 등 사용자 동작으로 호출할 때는 글루가 항상 준비되어 있으므로 대기가 필요 없습니다.

window.addEventListener('unveilyGlueReady', () => {
  // 이 시점부터 window.unveilyBridge.auth.* 호출이 안전합니다.
}, { once: true });

Android / iOS 플랫폼별 차이

JS API는 Android와 iOS 모두 동일합니다. 프로바이더별 네이티브 구현만 다릅니다.

프로바이더AndroidiOS
GoogleFirebase Auth (google-services.json) — idToken 반환Firebase Auth (GoogleService-Info.plist) — idToken 반환
AppleFirebase Auth (apple.com 프로바이더) — Firebase idToken 반환네이티브 Sign in with Apple — idToken + authorizationCode 반환
KakaoKakao SDK향후 iOS SDK 업데이트에서 제공 예정
NaverNaver SDK향후 iOS SDK 업데이트에서 제공 예정
LineLINE SDK향후 iOS SDK 업데이트에서 제공 예정
MetaFacebook SDK향후 iOS SDK 업데이트에서 제공 예정

Apple 로그인

Android의 Apple 로그인은 Firebase Auth의 apple.com 프로바이더로 처리되며 Firebase idToken을 반환합니다. (과거의 Web OAuth / 커스텀 callbackUrl 방식은 폐기되었습니다.) iOS의 Apple 로그인은 네이티브 Sign in with Apple을 사용하며, idToken에 더해 Apple 전용 authorizationCode를 함께 반환합니다.

iOS의 Kakao / Naver / Line / Meta

kakao, naver, line, metaAndroid에서 현재 모두 사용 가능합니다. iOS에서는 현재 Apple과 Google만 활성화되어 있어, 그 외 프로바이더는 SDK_NOT_READY 오류를 반환할 수 있습니다. 이들 프로바이더의 iOS 지원은 향후 SDK 업데이트에서 제공될 예정입니다.


API

socialLogin

소셜 로그인을 실행합니다. callback은 결과를 받을 전역 함수의 이름 문자열이며, 생략하면 기본값 onSocialLoginResult가 사용됩니다. 위치 인자 형태 socialLogin(provider, callback)도 지원합니다.

window.unveilyBridge.auth.socialLogin({
  provider: "google",   // "google" | "apple" | "kakao" | "naver" | "line" | "meta"
  callback: "onSocialLoginResult"
});

// 위치 인자 형태도 동일하게 동작합니다:
// window.unveilyBridge.auth.socialLogin("google", "onSocialLoginResult");

function onSocialLoginResult(result) {
  if (!result.success) {
    // 실패 — { success:false, provider, error, requiredTier? }
    console.error("로그인 실패:", result.provider, result.error, result.requiredTier);
    return;
  }

  const { provider, uid, displayName, email, profileImage, idToken } = result;

  // idToken은 google, apple 에서만 제공됩니다 (Firebase).
  // 서버로 전달하여 검증하세요.
  if (idToken) sendToServer({ provider, idToken });
}

결과는 JSON 객체

콜백은 문자열이 아닌 JSON 객체 하나를 인자로 받습니다. JSON.parse()가 필요 없습니다.

성공 응답 구조

{
  "success": true,
  "provider": "google",
  "uid": "firebase-or-provider-uid",
  "displayName": "홍길동",
  "email": "[email protected]",
  "profileImage": "https://...",
  "idToken": "eyJ..."
}
  • idTokengoogle, apple 에서만 포함됩니다 (Firebase). kakao / naver / line / meta 는 네이티브 SDK로 처리되며 idToken이 없습니다.
  • iOS의 Apple 로그인은 여기에 더해 Apple 전용 authorizationCode 필드를 반환합니다.

실패 응답 구조

{
  "success": false,
  "provider": "kakao",
  "error": "FEATURE_NOT_ALLOWED",
  "requiredTier": "standard"
}

requiredTier는 플랜 부족으로 실패한 경우 필요한 최소 플랜을 알려줍니다. UI에서 업그레이드 안내에 활용할 수 있습니다.

logout

현재 로그인된 소셜 계정에서 로그아웃합니다. callback 기본값은 onSocialAuthResult 입니다.

window.unveilyBridge.auth.logout({
  provider: "kakao",
  callback: "onSocialAuthResult"
});

revoke

소셜 계정 연동을 해제합니다. (앱에서 완전한 탈퇴 처리 시 사용) callback 기본값은 onSocialAuthResult 입니다.

window.unveilyBridge.auth.revoke({
  provider: "google",
  callback: "onSocialAuthResult"
});

function onSocialAuthResult(result) {
  // { success, action: "logout" | "revoke", provider, error? }
  console.log(result.action, result.provider, result.success);
}

오류 코드

로그인 / 로그아웃 / 해제 실패 시 error 필드에 다음 중 하나가 반환됩니다.

코드의미
INVALID_PARAMS필수 파라미터 누락 또는 형식 오류
FEATURE_NOT_ALLOWED현재 플랜에서 허용되지 않는 프로바이더 (requiredTier 참고)
PROVIDER_DISABLED해당 프로바이더가 설정에서 비활성화됨
SDK_NOT_CONFIGURED프로바이더 SDK 설정 누락 (키/클라이언트 ID 등)
SDK_NOT_READYSDK가 아직 준비되지 않음 (예: iOS의 Apple/Google 외 프로바이더)
UNKNOWN_PROVIDER인식할 수 없는 프로바이더 이름
LOGIN_CANCELLED사용자가 로그인 창을 닫음

서버측 토큰 검증

idToken은 반드시 서버에서 검증해야 합니다. 클라이언트에서만 처리하지 마세요. idToken은 google, apple 로그인에서만 제공됩니다.

소셜 로그인 성공 후 받은 idToken을 서버에 전달하여 검증합니다.

// Express.js 예시
const { OAuth2Client } = require('google-auth-library');
const client = new OAuth2Client(process.env.GOOGLE_CLIENT_ID);

app.post('/api/auth/social', async (req, res) => {
  const { provider, idToken } = req.body;

  if (provider === 'google') {
    const ticket = await client.verifyIdToken({
      idToken,
      audience: process.env.GOOGLE_CLIENT_ID
    });
    const payload = ticket.getPayload();
    const user = await findOrCreateUser({ email: payload.email, name: payload.name });
    const sessionToken = generateSessionToken(user);
    res.json({ token: sessionToken, user });
  }
});
// ASP.NET Core 예시
[HttpPost("auth/social")]
public async Task<IActionResult> SocialLogin([FromBody] SocialLoginRequest request)
{
    if (request.Provider == "google")
    {
        var payload = await GoogleJsonWebSignature.ValidateAsync(request.IdToken,
            new GoogleJsonWebSignature.ValidationSettings {
                Audience = new[] { _config["Google:ClientId"] }
            });

        var user = await _userService.FindOrCreateAsync(payload.Email, payload.Name);
        var token = _tokenService.Generate(user);
        return Ok(new { token, user });
    }
    return BadRequest();
}
// Spring Boot 예시
@PostMapping("/api/auth/social")
public ResponseEntity<?> socialLogin(@RequestBody SocialLoginRequest request) {
    if ("google".equals(request.getProvider())) {
        GoogleIdTokenVerifier verifier = new GoogleIdTokenVerifier.Builder(
            new NetHttpTransport(), JacksonFactory.getDefaultInstance())
            .setAudience(Collections.singletonList(googleClientId))
            .build();

        GoogleIdToken idToken = verifier.verify(request.getIdToken());
        if (idToken != null) {
            GoogleIdToken.Payload payload = idToken.getPayload();
            User user = userService.findOrCreate(payload.getEmail(), (String) payload.get("name"));
            String token = tokenService.generate(user);
            return ResponseEntity.ok(Map.of("token", token, "user", user));
        }
    }
    return ResponseEntity.badRequest().build();
}
<?php
// PHP 예시 (google-api-php-client 사용)
require_once 'vendor/autoload.php';

$client = new Google_Client(['client_id' => $_ENV['GOOGLE_CLIENT_ID']]);

$data = json_decode(file_get_contents('php://input'), true);
if ($data['provider'] === 'google') {
    $payload = $client->verifyIdToken($data['idToken']);
    if ($payload) {
        $user = findOrCreateUser($payload['email'], $payload['name']);
        $token = generateToken($user);
        echo json_encode(['token' => $token, 'user' => $user]);
    } else {
        http_response_code(401);
    }
}
<%
' Classic ASP 예시 — Google 토큰 검증은 서버사이드 라이브러리 또는
' Google tokeninfo 엔드포인트를 통해 처리합니다.
Dim idToken, provider
idToken = Request.Form("idToken")
provider = Request.Form("provider")

If provider = "google" Then
    ' Google tokeninfo API 호출
    Dim url, http
    url = "https://oauth2.googleapis.com/tokeninfo?id_token=" & idToken
    Set http = Server.CreateObject("MSXML2.ServerXMLHTTP")
    http.Open "GET", url, False
    http.Send

    If http.Status = 200 Then
        ' 검증 성공 — 사용자 처리
        Response.ContentType = "application/json"
        Response.Write "{""success"": true}"
    Else
        Response.Status = "401 Unauthorized"
    End If
End If
%>

On this page