{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/embedded-widget/quickstart","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"SDK Quickstart","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"sdk-quickstart","__idx":0},"children":["SDK Quickstart"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Install the SDK in the issuer host application and mount it into a stable container."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ts","header":{"controls":{"copy":{}}},"source":"import { Percents } from '@percents/web-sdk';\n\nconst widget = Percents.init({\n  container: '#percents-widget',\n  sessionEndpoint: '/api/percents/session',\n  view: 'offers',\n  appearance: {\n    displayName: 'Branded Rewards',\n    primaryColor: '#0079d2',\n    accentColor: '#028a00',\n    fontFamily: \"Gilroy, 'Gilroy Regular', ui-sans-serif, system-ui\",\n  },\n});\n\nwidget.on('merchant_activation_completed', (payload) => {\n  console.log('Merchant activated', payload);\n});\n","lang":"ts"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"session-endpoint","__idx":1},"children":["Session Endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionEndpoint"]}," is owned by the issuer. It authenticates the current user, resolves the cardholder group, mints or retrieves a proxy session, and returns:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"widgetUrl\": \"https://widgets.percents.com/embed/index.html\",\n  \"proxyApiBaseUrl\": \"https://issuer.example.com/api/percents/proxy\",\n  \"proxySessionToken\": \"opaque-session-token\",\n  \"expiresAt\": \"<RFC3339 expiration timestamp>\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store the proxy session and its upstream widget token only on the issuer server. Use a shared, durable session store when the proxy runs on more than one instance."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"proxy-api","__idx":2},"children":["Proxy API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The iframe calls the issuer proxy with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <proxySessionToken>"]},". The proxy validates the session, enforces the CHG scope, forwards the request to Percents, and strips any server-only credentials from browser-visible responses."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When creating the upstream widget session, the proxy authenticates to Percents with a signed mint assertion verified through the issuer's JWKS. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/auth-security/sdk-auth#production-mint-authentication"},"children":["SDK Authentication"]}," for the required request, claims, and registration details."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sandbox-testing","__idx":3},"children":["Sandbox Testing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To test the SDK before production, deploy an issuer sandbox proxy that forwards to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://sandbox.percents.com"]},". Do not point the browser directly at Percents or embed a long-lived API token in the page."]}]},"headings":[{"value":"SDK Quickstart","id":"sdk-quickstart","depth":1},{"value":"Session Endpoint","id":"session-endpoint","depth":2},{"value":"Proxy API","id":"proxy-api","depth":2},{"value":"Sandbox Testing","id":"sandbox-testing","depth":2}],"frontmatter":{"seo":{"title":"SDK Quickstart"}},"lastModified":"2026-07-21T18:22:26.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/embedded-widget/quickstart","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}