본문으로 건너뛰기

getServerTime

토스 앱 서버의 현재 시간을 Unix timestamp 밀리초 단위로 비동기적으로 반환합니다. 클라이언트 기기 시간이 아닌 서버 기준 시간을 사용하므로, 보상 지급·만료 판단 등 클라이언트 시간 조작을 방지해야 하는 로직에 적합합니다. 지원하지 않는 앱 버전에서는 undefined를 반환합니다.

이 함수는 getServerTime.isSupported() 정적 메서드를 통해 현재 앱 버전에서 기능 지원 여부를 미리 확인할 수 있습니다.

시그니처​

import { getServerTime } from '@apps-in-toss/web-framework';

declare function getServerTime(): Promise<number | undefined>;
declare namespace getServerTime {
  var isSupported: () => boolean;
}

getServerTime.isSupported()​

현재 앱 버전이 getServerTime을 지원하는지 확인합니다. 지원하지 않는 버전에서 getServerTime()을 호출하면 undefined를 반환하므로, 호출 전 isSupported()로 버전 체크를 먼저 수행하는 것을 권장합니다.

declare function isSupported(): boolean;

파라미터​

없음.

반환값​

  • Promise<number | undefined> — 서버 시간(Unix timestamp, 밀리초). 예: 1705123456789. 지원하지 않는 앱 버전에서는 undefined.
undefined 처리 필수

지원하지 않는 앱 버전에서는 undefined가 반환됩니다. 반환값을 직접 사용하기 전에 반드시 undefined 여부를 확인하거나, getServerTime.isSupported()로 먼저 체크하세요.

권한​

권한이 필요하지 않습니다 — getServerTime은 별도의 PermissionName에 바인딩되지 않습니다. 권한이 필요한 다른 네임스페이스의 일반적인 처리 흐름은 Guides — 권한 처리 패턴을 참고하세요.

예제​

최소 예제​

import { getServerTime } from '@apps-in-toss/web-framework';

if (getServerTime.isSupported()) {
  const serverTime = await getServerTime();
  console.log('서버 시간(ms):', serverTime);
}

실전 예제 — 보상 수령 기간 판단​

import { getServerTime } from '@apps-in-toss/web-framework';
import { useState, useEffect } from 'react';

const REWARD_DEADLINE_MS = 1705200000000; // 예: 2024-01-14 00:00:00 UTC

function RewardPage() {
  const [status, setStatus] = useState<'loading' | 'available' | 'expired' | 'unsupported'>('loading');

  useEffect(() => {
    async function checkDeadline() {
      if (!getServerTime.isSupported()) {
        setStatus('unsupported');
        return;
      }

      const serverTime = await getServerTime();

      if (serverTime === undefined) {
        setStatus('unsupported');
        return;
      }

      setStatus(serverTime <= REWARD_DEADLINE_MS ? 'available' : 'expired');
    }

    checkDeadline();
  }, []);

  const messages = {
    loading: '확인 중...',
    available: '보상을 수령할 수 있습니다.',
    expired: '보상 수령 기간이 지났습니다.',
    unsupported: '이 기능은 현재 앱 버전에서 지원되지 않습니다.',
  };

  return <p>{messages[status]}</p>;
}

직접 실행해 보기​

sdk-example의 Environment 페이지에서 getServerTime 카드를 실행해 결과를 확인할 수 있습니다.

sdk-example에서 실행해 보기

관련 API​

관련 가이드​

외부 참조​

  • @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/web-bridge에서 가져옵니다.
  • 표준 Web API 대응: Date.now() — 클라이언트 기기 시간을 반환하며, 사용자가 기기 시간을 조작하면 값이 달라집니다. 치팅 방지가 필요한 경우 getServerTime()을 사용하세요.