AltsCodex SDK — Frontend / Client Guide

Environment Environment Setup 환경변수 설정

The SDK does not read process.env or import.meta.env itself — it accepts plain options. Inject them from your build environment so secrets stay out of source code. SDK 자체는 process.env / import.meta.env 를 읽지 않습니다. 옵션으로 직접 전달받습니다. 빌드 환경에서 .env 로 주입해 시크릿이 소스코드에 남지 않도록 하세요.

Vite (frontend SPA) Vite (프론트엔드 SPA)

# .env.production
VITE_ALTSCODEX_URL=https://altscodex.com
VITE_CLIENT_ID=your-registered-client-id
VITE_REDIRECT_URI=https://yourapp.com/callback

// AuthContext.tsx
import AltsCodex from '@altscodex/sdk';

const sdk = new AltsCodex({
  altscodexUrl: import.meta.env.VITE_ALTSCODEX_URL,
  clientId:     import.meta.env.VITE_CLIENT_ID,
  redirectUri:  import.meta.env.VITE_REDIRECT_URI,
});

Next.js / Node backend Next.js / Node 백엔드

# .env.local (server side)
ALTSCODEX_AUTH_SERVER_URL=https://api.altscodex.com
ALTSCODEX_CLIENT_ID=your-registered-client-id
ALTSCODEX_CLIENT_SECRET=your-client-secret    # NEVER expose to the browser
ALTSCODEX_REDIRECT_URI=https://yourapp.com/getinfo

Use a separate .env.<mode> file per environment (local / staging / production). Vite picks the file by --mode; Next.js picks by NODE_ENV. 환경별로 .env.<mode> 파일을 분리하세요. Vite 는 --mode 로, Next.js 는 NODE_ENV 로 파일을 선택합니다.

Pitfalls ⚠️ Common Pitfalls ⚠️ 자주 부딪히는 함정

1. Use the registered hosts only 1. 등록된 호스트만 사용하세요

Do NOT invent subdomains like login.altscodex.com, oauth.altscodex.com, auth.altscodex.com. They resolve to NXDOMAIN and the popup silently fails with User closed the login window after a long timeout. login.altscodex.com, oauth.altscodex.com, auth.altscodex.com 같은 미등록 서브도메인을 임의로 사용하지 마세요. NXDOMAIN 이 떨어지고 팝업이 한참 후 User closed the login window 로 조용히 실패합니다.

2. Register your clientId and redirectUri first 2. clientId / redirectUri 사전 등록 필수

Register your application here at the Developer Center to obtain a clientId and clientSecret. Hard-coding values that are not registered (or a redirectUri that does not exactly match the registered value — including trailing slash) results in invalid_client / redirect_uri mismatch 401 errors. 개발자 센터에서 애플리케이션을 등록해 clientId / clientSecret 을 발급받으세요. 미등록 값을 박거나 redirectUri 가 등록된 값과 정확히 일치하지 않으면 (트레일링 슬래시 포함) invalid_client / redirect_uri mismatch 401 오류가 발생합니다.

3. Migrating from @webxcom/sdk v1.x 3. @webxcom/sdk v1.x 에서 마이그레이션

Coexistence: the platform server emits postMessage in dual-broadcast mode — one with from: "altscodex" (consumed by v2.x SDK) and a second with from: "webxcom" (consumed by v1.x SDK). Existing v1.x apps continue to work unchanged during gradual migration. 양립 호환: 플랫폼 서버는 dual-broadcast 로 동작합니다. from: "altscodex" (v2.x SDK 수신) 과 from: "webxcom" (v1.x SDK 수신) 두 메시지를 동시에 발송합니다. 옛 v1.x 앱은 코드 변경 없이 동작합니다.

4. Cross-Origin-Opener-Policy (COOP) caveat 4. Cross-Origin-Opener-Policy (COOP) 주의

If your hosting page sets Cross-Origin-Opener-Policy: same-origin, the browser may block the SDK's popup.closed poll. The SDK degrades gracefully (stops polling and relies on postMessage + timeout), but a user closing the popup with the X button may not be detected. Recommended COOP for OAuth opener pages: same-origin-allow-popups or unsafe-none. 호스팅 페이지가 Cross-Origin-Opener-Policy: same-origin 을 보내면 SDK 의 popup.closed 폴링이 차단될 수 있습니다. SDK 는 graceful 하게 폴링을 중단하고 postMessage + timeout 으로 종료를 결정하지만, 사용자가 X 로 닫는 케이스는 감지 못할 수 있습니다. OAuth 팝업을 여는 페이지의 권장 COOP 정책: same-origin-allow-popups 또는 unsafe-none.

Unity Unity SDK (WebGL + Standalone only) Unity SDK (WebGL + Standalone 전용)

If your client is a Unity game, use the Unity SDK instead of the browser JavaScript SDK. It mirrors the same login flow (popup + JWT) but exposes a single async C# API: await AltsCodexLogin.LoginAsync(config). 클라이언트가 Unity 게임이라면 브라우저 JavaScript SDK 대신 Unity SDK 를 사용하세요. 동일한 로그인 흐름(popup + JWT)을 그대로 재현하되 비동기 C# API 하나로 노출합니다: await AltsCodexLogin.LoginAsync(config).

Supported build targets 지원 빌드 타겟

Install (UPM Git URL) 설치 (UPM Git URL)

Open Window → Package Manager → + → Add package from git URL... and paste: Window → Package Manager → + → Add package from git URL... 에서 다음을 입력하세요:

https://github.com/alts-codex/unity-sdk.git#v0.1.0

Or edit Packages/manifest.json directly: 또는 Packages/manifest.json 을 직접 편집:

{
  "dependencies": {
    "com.alts-codex.auth-sdk": "https://github.com/alts-codex/unity-sdk.git#v0.1.0"
  }
}

Quick Start Quick Start

using System.Threading;
using UnityEngine;
using AltsCodex;

public class LoginButton : MonoBehaviour
{
    public async void OnClick()
    {
        var config = new LoginConfig
        {
            ClientId    = "YOUR_CLIENT_ID",          // Developer Center 발급
            RedirectUri = "https://yourgame.example.com/callback",
            // AltsCodexUrl 기본값: https://altscodex.com
        };

        var result = await AltsCodexLogin.LoginAsync(config);

        if (!result.Success)
        {
            Debug.LogWarning("login failed: " + result.ErrorMessage);
            return;
        }

        // result.Jwt 를 게임 백엔드로 전송 → 백엔드가 Node/Python/Go SDK 로 슬롯 정보 조회
        Debug.Log("JWT received, length=" + result.Jwt.Length);
    }
}

How each platform works 플랫폼별 동작 원리

• WebGL — C# LoginAsync calls into a bundled .jslib, which opens window.open(loginUrl) against altscodex.com. The popup posts back via postMessage and the bridge forwards the payload to C# through unityInstance.SendMessage(...). Your WebGL template must expose the instance: window.unityInstance = unityInstance; after createUnityInstance(...). C# LoginAsync 가 번들된 .jslib 를 호출해 altscodex.com 으로 window.open(loginUrl). popup 이 postMessage 로 응답하면 브릿지가 unityInstance.SendMessage(...) 로 C# 에 전달합니다. WebGL 템플릿에서 반드시 인스턴스를 노출해야 합니다: createUnityInstance(...) 호출 후 window.unityInstance = unityInstance;.
• Standalone — SDK binds http://127.0.0.1:<port>/callback via System.Net.HttpListener (ephemeral port by default, or pin via LoopbackPort), opens the OS default browser with Application.OpenURL, then waits for the platform server to redirect back with jwt + state query parameters. The Developer Center must whitelist this loopback URI (fixed port like http://127.0.0.1:17070/callback, or wildcard http://127.0.0.1:*/callback if supported). SDK 가 System.Net.HttpListener 로 http://127.0.0.1:<port>/callback 바인딩(기본 ephemeral, LoopbackPort 로 고정 가능), Application.OpenURL 로 OS 기본 브라우저 열기, 플랫폼 서버가 jwt + state 쿼리 파라미터로 리다이렉트 대기. Developer Center 에 이 loopback URI 를 등록해야 합니다(http://127.0.0.1:17070/callback 고정 포트, 또는 지원 시 http://127.0.0.1:*/callback 와일드카드).

Resources 참고 자료

• GitHub · alts-codex/unity-sdk — source, full README, issues 소스, 전체 README, 이슈
• Samples~/BasicLogin/BasicLoginExample.cs — runnable example scene script (Package Manager → Samples → Import) 실행 가능한 예제 씬 스크립트 (Package Manager → Samples → Import)
• Server SDK Guide (Node / Python / Go) — required companion 서버 SDK 가이드 (Node / Python / Go) — 함께 사용 필수