Skip to main content

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

Provider Setup

Wrap your app with TimebackProvider:
app/providers.tsx
app/layout.tsx

Hooks

useTimeback

Access the Timeback client:

useTimebackVerification

Check authentication status:
The 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:

Components

SignInButton

Pre-built sign-in button:

Props

size
'sm' | 'md' | 'lg'
default:"'md'"
Button size
variant
'default' | 'outline'
default:"'default'"
Button style variant
showLoading
boolean
default:"true"
Show loading spinner on click
Show Timeback logo
disabled
boolean
default:"false"
Disable the button
className
string
Additional CSS classes
style
CSSProperties
Inline styles
onClick
() => void
Additional click handler
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