A integração de login social utilizando o QQ JS SDK é altamente simplificada, exigindo um esforço mínimo de configuração no lado do cliente. A plataforma fornece um carrregador de script que gerencia o fluxo de autenticação de forma transparente.

Configuração do Carregador do SDK

O primeiro passo é incluir o script oficial do QQ Connect. Uma particularidade da plataforma QQ é a necessidade de gerenciar identificadores de aplicação (AppID) distintos para ambientes desktop e mobile. Além disso, para garantir um identificador único do usuário entre diferentes aplicações, é recomendável solicitar o unionid no backend após receber o openid.

O atributo data-callback="true" é utilizado para indicar que a página atual atuará como o ponto de retorno após a autenticação. Isso centraliza o tratamento do callback, evitando a necessidade de criar páginas intermediárias apenas para capturar o token.

@section Scripts {
    <script>
        // Detecção de dispositivo para seleção do AppID correto
        const isMobileDevice = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
        const currentAppId = isMobileDevice ? "@Model.MobileAppId" : "@Model.DesktopAppId";
    </script>
    
    <script src="https://qzonestyle.gtimg.cn/qzone/openapi/qc_loader.js"
            data-appid="@Model.AppId"
            data-redirecturi="@Model.CallbackUrl"
            data-callback="true"
            charset="utf-8"></script>
}

Implementação do Fluxo de Login e Callback

O método QC.Login é responsável por renderizar o botão de autenticação e gerenciar os eventos de sucesso e falha. No callback de sucesso, a interface do usuário é atualizada com os dados do perfil (como avatar e nickname) e o sistema deve redirecionar o usuário para o endpoint do backend, passando o openid e o accessToken.

Um comportamento crítico a ser observado é a diferença de navegação entre PC e dispositivos móveis (WAP). No desktop, o QQ abre uma janela pop-up que é fechada automaticamente após o login. Em navegadores mobile, a autenticação ocorre na mesma aba, o que pode causar conflitos de redirecionamento e travar a execução do QC.Login.check(). Para contornar isso em ambientes mobile, aplica-se um atraso (setTimeout) antes de executar o redirecionamento final.

document.addEventListener("DOMContentLoaded", function() {
    const authButtonId = "btnQqLogin";
    const isMobile = /Android|webOS|iPhone|iPod|BlackBerry/i.test(navigator.userAgent);

    QC.Login({
        btnId: authButtonId,
        scope: "get_user_info",
        size: "B_M"
    }, function(userData, options) {
        // Atualização da interface com os dados do usuário autenticado
        const container = document.getElementById(options.btnId);
        if (container) {
            container.innerHTML = `
                <div class="user-session">
                    <img src="${userData.figureurl}" alt="Avatar" class="avatar" />
                    <span class="nickname">${QC.String.escHTML(userData.nickname)}</span>
                    <a href="javascript:void(0);" onclick="QC.Login.signOut();">Encerrar Sessão</a>
                </div>
            `;
        }

        // Função para processar o redirecionamento com os tokens
        const processRedirect = () => {
            QC.Login.getMe(function(openId, accessToken) {
                const params = new URLSearchParams({
                    handler: 'R',
                    name: userData.nickname,
                    openid: openId,
                    otype: '1',
                    token: accessToken
                });
                window.location.href = `/account/external-login?${params.toString()}`;
            });
        };

        // Aplica delay apenas em dispositivos móveis para evitar conflitos de redirecionamento
        if (isMobile) {
            setTimeout(processRedirect, 2500);
        } else {
            processRedirect();
        }
    }, function() {
        // Callback de logout
        window.location.href = "/";
    });
});

Tratamento de Erros Conhecidos

Durante a integração, é comum deparar-se com o erro [QQConnect] > access_token丢失 : _getMeError nos logs do console. Na maioria dos cenários práticos, essa notificação não impacta a fluidez do fluxo de autenticação nem a obtenção correta dos dados do usuário no backend, podendo ser tratada como um aviso não bloqueante pela equipe de desenvolvimento.