Skip to main content
Unveilydocs

Social Login Bridge

Native social login bridge (Google, Apple, Kakao, Naver, Line, Meta)

Overview

The unveilyBridge.auth namespace lets you open a native social login window from your web page and receive the result. For social login SDK setup, refer to the Social Login Setup document.

Supported providers: google, apple, kakao, naver, line, meta

Minimum plan by provider

ProviderMin planBasicStandardPro
GoogleBasic
AppleBasic
KakaoStandard
NaverStandard
LineStandard
Meta (Facebook)Pro

Google and Apple are available from the Basic plan. Kakao / Naver / Line require Standard, and Meta requires Pro.


Readiness — unveilyGlueReady

window.unveilyBridge is registered before the page loads, but the auth namespace only becomes available after the glue script injects. If you call auth.* at mount time in an SPA, wait for the unveilyGlueReady event first. Calls made from a user gesture (e.g. a button click) don't need to wait — the glue is always ready by then.

window.addEventListener('unveilyGlueReady', () => {
  // From here, window.unveilyBridge.auth.* calls are safe.
}, { once: true });

Android / iOS Platform Differences

The JS API is identical on both Android and iOS. Only the native implementation per provider differs.

ProviderAndroidiOS
GoogleFirebase Auth (google-services.json) — returns idTokenFirebase Auth (GoogleService-Info.plist) — returns idToken
AppleFirebase Auth (apple.com provider) — returns Firebase idTokenNative Sign in with Apple — returns idToken + authorizationCode
KakaoKakao SDKComing in a future iOS SDK update
NaverNaver SDKComing in a future iOS SDK update
LineLINE SDKComing in a future iOS SDK update
MetaFacebook SDKComing in a future iOS SDK update

Apple Login

Apple login on Android is handled via the Firebase Auth apple.com provider and returns a Firebase idToken. (The old Web OAuth / custom callbackUrl model has been retired.) On iOS, Apple login uses native Sign in with Apple and returns an Apple-only authorizationCode in addition to the idToken.

Kakao / Naver / Line / Meta on iOS

kakao, naver, line, and meta are fully available on Android now. On iOS, only Apple and Google are currently enabled, so the other providers may return an SDK_NOT_READY error. iOS support for these providers is coming in a future SDK update.


API

socialLogin

Initiates social login. callback is the name string of the global function that will receive the result; if omitted, the default onSocialLoginResult is used. The positional form socialLogin(provider, callback) also works.

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

// The positional form works identically:
// window.unveilyBridge.auth.socialLogin("google", "onSocialLoginResult");

function onSocialLoginResult(result) {
  if (!result.success) {
    // Failure — { success:false, provider, error, requiredTier? }
    console.error("Login failed:", result.provider, result.error, result.requiredTier);
    return;
  }

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

  // idToken is provided only for google and apple (Firebase).
  // Forward it to your server to verify.
  if (idToken) sendToServer({ provider, idToken });
}

Result is a JSON object

The callback receives a single JSON object as its argument, not a string. No JSON.parse() is needed.

Success response structure

{
  "success": true,
  "provider": "google",
  "uid": "firebase-or-provider-uid",
  "displayName": "John Doe",
  "email": "[email protected]",
  "profileImage": "https://...",
  "idToken": "eyJ..."
}
  • idToken is included only for google and apple (Firebase). kakao / naver / line / meta are handled by native SDKs and have no idToken.
  • On iOS, Apple login additionally returns an Apple-only authorizationCode field.

Failure response structure

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

requiredTier tells you the minimum plan needed when a login fails due to insufficient plan. Use it to drive an upgrade prompt in your UI.

logout

Logs out of the currently logged-in social account. The callback default is onSocialAuthResult.

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

revoke

Disconnects the social account. (Use this for full account deletion from the app.) The callback default is 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 Codes

On a failed login / logout / revoke, the error field returns one of the following.

CodeMeaning
INVALID_PARAMSMissing or malformed required parameter
FEATURE_NOT_ALLOWEDProvider not permitted on the current plan (see requiredTier)
PROVIDER_DISABLEDThe provider is disabled in configuration
SDK_NOT_CONFIGUREDProvider SDK configuration missing (key / client ID, etc.)
SDK_NOT_READYSDK not ready yet (e.g. non-Apple/Google providers on iOS)
UNKNOWN_PROVIDERUnrecognized provider name
LOGIN_CANCELLEDUser dismissed the login window

Server-side Token Verification

The idToken must be verified on the server. Do not handle it on the client only. idToken is provided only for google and apple logins.

After a successful social login, pass the received idToken to the server for verification.

// Express.js example
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 example
[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 example
@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 example (using 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 example — verify the Google token with a server-side library
' or the Google tokeninfo endpoint.
Dim idToken, provider
idToken = Request.Form("idToken")
provider = Request.Form("provider")

If provider = "google" Then
    ' Call the 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
        ' Verification succeeded — handle the user
        Response.ContentType = "application/json"
        Response.Write "{""success"": true}"
    Else
        Response.Status = "401 Unauthorized"
    End If
End If
%>

On this page