Overview
The Timeback SDK provides React hooks, components, and a context provider for client-side integration.
If you are using coding agents, pair this page with timeback-client from the AI Skills catalog.
Installation
npm install @timeback/sdk
Provider Setup
Wrap your app with TimebackProvider:
'use client'
import { TimebackProvider } from '@timeback/sdk/react'
export function Providers({ children }: { children: React.ReactNode }) {
return <TimebackProvider>{children}</TimebackProvider>
}
import { Providers } from './providers'
export default function RootLayout({ children }) {
return (
<html>
<body>
<Providers>{children}</Providers>
</body>
</html>
)
}
Hooks
useTimeback
Access the Timeback client:
import { useTimeback } from '@timeback/sdk/react'
function MyComponent() {
const timeback = useTimeback()
// timeback is null if user is not authenticated
if (!timeback) {
return <div>Please sign in</div>
}
return <div>Welcome!</div>
}
useTimebackVerification
Check authentication status:
import { useTimebackVerification } from '@timeback/sdk/react'
function ProtectedRoute({ children }) {
const { state, refresh } = useTimebackVerification()
if (state.status === 'loading') return <div>Loading...</div>
if (state.status !== 'verified') return <Navigate to="/login" />
return children
}
state object has a status property that can be:
'loading' - Verification in progress'verified' - User is verified (includes timebackId)'unverified' - User is not verified'error' - Verification failed (includes message)
useTimebackProfile
Fetch user profile data:
import { useTimebackProfile } from '@timeback/sdk/react'
// Manual fetch
function ProfileButton() {
const { state, canFetch, fetchProfile } = useTimebackProfile()
if (state.status === 'loaded') {
return (
<div>
<p>Welcome, {state.profile.name}</p>
<p>XP Today: {state.profile.xp.today}</p>
<p>Total XP: {state.profile.xp.all}</p>
</div>
)
}
return (
<button onClick={fetchProfile} disabled={!canFetch}>
{state.status === 'loading' ? 'Loading...' : 'Load Profile'}
</button>
)
}
// Auto-fetch when authenticated
function AutoProfile() {
const { state } = useTimebackProfile({ auto: true })
if (state.status === 'loading') return <div>Loading...</div>
if (state.status === 'loaded') {
return <div>XP: {state.profile.xp.today}</div>
}
return null
}
Components
Pre-built sign-in button:
import { SignInButton } from '@timeback/sdk/react'
function LoginPage() {
return (
<div>
<h1>Welcome</h1>
<SignInButton size="lg">Sign in with Timeback</SignInButton>
</div>
)
}
Props
size
'sm' | 'md' | 'lg'
default:"'md'"
Button size
variant
'default' | 'outline'
default:"'default'"
Button style variant
Show loading spinner on click
children
ReactNode
default:"'Sign In'"
Button text
Custom Activities
The SDK supports two activity models that capture how students spend time in your app and whether they complete what they started, producing TimeSpentEvents and ActivityCompletedEvents that feed into dashboards, XP, and learning analytics.
Single-session
A quiz, flashcard deck, or short lesson that a student completes in one sitting. The client tracks time and reports completion. Learn more about single-session activities.
Stateful
A multi-part course or long-form project where students leave and come back across multiple sessions. The client tracks time per visit while the server records completion. Learn more about stateful activities.
Next Steps
Next.js Server
Server-side setup
Custom Activities
Learn more about tracking
