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

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