Skip to main content
Partner SDK: Embed ActionFi directly into your platform. Your users complete training tasks without leaving your site, you get attribution for every completion, and the LAM gets valuable training data. Everyone wins.

What is the Partner SDK?

The ActionModel Partner SDK lets you embed the ActionFi training widget directly into your website or application. Instead of sending users to the ActionFi dashboard, they can discover and complete training tasks right inside your platform.

Seamless Integration

Users stay on your platform while completing ActionFi tasks

User Attribution

Link completions to your user accounts for rewards tracking

Custom Theming

Match the widget to your brand with full color customization
Who is this for? The Partner SDK is for platforms that have partnered with ActionFi and want to embed training tasks directly into their product. If you’re not yet a partner, apply here.

Quick Start

Get the widget running in under 5 minutes with this minimal setup.
1

Step 0: Configure npm Access (Private Package)

The npm package is private. You need a token from ActionModel to install via npm.
  1. Request a token: contact the partner onboarding team and ask for an npm deploy token with read_package_registry scope for the Partner SDK.
  2. Add .npmrc (project root) or ~/.npmrc (global):
  1. Export the token (local dev):
Do not commit tokens. Prefer env var substitution as shown above.
2

Add the Container

Create a div element where you want the widget to appear. Give it enough height for the task list.
3

Load the SDK

Load the SDK.CDN/UMD (no bundler):
npm (bundlers / React / Vue):
4

Initialize the Widget

Call ActionModel.init() with your Partner ID to render the widget.
Partner ID: Your Partner ID is a UUID provided when you sign up as an ActionModel partner. Contact the partner onboarding team if you don’t have one.

Complete Quick Start Example


Installation


Configuration Options

The ActionModel.init() function accepts a configuration object with the following options:

Required Options

Optional Options

Minimal configuration with just the required options:
Complete configuration using all available options:
By default, the widget shows tasks for your current domain. You can override this:
This is useful if:
  • Your widget is on a different subdomain than where tasks are completed
  • You want to preview tasks from another domain during development
Filter to show only tasks from a specific bounty campaign:
Use this when running limited-time campaigns or themed task sets.

TypeScript Interfaces

For TypeScript projects, these are the public types exported by the SDK (authoritative for npm installs):
Using with TypeScript: Copy these interfaces into a actionmodel.d.ts file in your project to get full type checking and autocompletion.

User Identification

Link task completions to your users for attribution and analytics. When you identify users, their completions are permanently mapped to your internal user ID.
Important: The externalId creates a permanent mapping between your user and ActionModel. Use a stable identifier that won’t change (e.g., database user ID, not email address).

User Object Properties

Basic User Identification

Full User Identification

Metadata Use Cases: The metadata object can contain any JSON-serializable data. Use it to segment users in your analytics, personalize experiences, or track attribution across your systems.

Dynamic User Identification

If your user logs in after the widget is initialized, destroy and reinitialize:

Theming

Customize the widget to match your brand. The theme option supports mode, semantic tokens (sys), component tokens (comp), border radius, and font family.

Presets


Events

Subscribe to widget events for analytics, custom behavior, or debugging.

Event Handler Setup

Event Types Reference

Event Handling Examples

Send events to your analytics platform:
Show a custom prompt when the extension isn’t installed:
Handle errors gracefully:
Track when users engage with tasks:

Configuring Webhooks

Coming Soon: Webhook configuration is currently being updated. This section will be expanded with full documentation shortly.
Webhooks allow you to receive real-time notifications on your server when events occur in the ActionModel widget, such as task completions, user registrations, and training sessions.

What’s Coming

Task Completion Webhooks

Receive POST requests when users complete training tasks, including task ID, user data, and completion metadata.

User Activity Events

Get notified when users start training sessions, reach milestones, or achieve rewards.

Secure Signatures

All webhook payloads will be signed with HMAC-SHA256 for verification.

Retry Logic

Failed deliveries will be retried with exponential backoff to ensure reliability.

Interested in Early Access?

Contact the partner onboarding team to discuss webhook integration for your platform.

Instance Methods

The init() function returns a widget instance with methods for controlling the widget.

refresh()

Reload tasks from the server. Useful after user actions that might affect available tasks.

destroy()

Remove the widget and clean up all event listeners. Always call this before reinitializing or when the widget is no longer needed.

ActionModel.destroyAll()

Static method to destroy all widget instances on the page. Useful in single-page applications.

Framework Integration

React Integration

Use the React wrapper from @actionmodel/partner-sdk/react.
Usage:For imperative control, use the hook:

Requirements

Before integrating the Partner SDK, ensure you have:

Partner Integration

Partner ID RequiredYour partnerId must be configured in the ActionModel system. Contact the partner onboarding team to get started.

Domain Whitelisting

Domain Must Be AllowedYour domain must be whitelisted for your partner integration. This is configured when you sign up as a partner.

Browser Extension

Users Need the ExtensionUsers must have the ActionModel browser extension installed to complete training tasks. The widget will show an install prompt if not detected.

HTTPS Required

Secure ConnectionThe SDK requires HTTPS in production. Development on localhost is supported.

Supported Browsers

The ActionModel browser extension supports:

Troubleshooting

Problem: npm install @actionmodel/partner-sdk fails with authentication or not found errors.Fix: Configure .npmrc for the private registry and provide a token from ActionModel.
Then export the token:
If you don’t have a token, contact the partner onboarding team.
Problem: The widget displays a message that the extension is not found.Solutions:
  1. Ensure extension is installed: Users must install the ActionModel browser extension from the Chrome Web Store
  2. Check browser compatibility: The extension supports Chrome-family browsers (Chrome, Edge, Brave, Arc, Opera, Mises)
  3. Verify extension is enabled: Check chrome://extensions to ensure it’s not disabled
  4. Try refreshing: Sometimes the extension takes a moment to register. Call widget.refresh() or reload the page
Problem: The widget shows an access denied error.Solutions:
  1. Verify your partnerId: Ensure the Partner ID is correct and matches what was provided
  2. Check domain whitelisting: Your domain must be allowed in your partner configuration
  3. Confirm partner status: Ensure your partner integration is active and enabled
  4. Contact support: Contact the partner onboarding team with your Partner ID and domain
Problem: The widget loads but shows no tasks.Solutions:
  1. Verify domain configuration: Ensure tasks are configured for your domain or the specified domain parameter
  2. Check bountyId: If filtering by bounty, verify the bounty ID is correct
  3. Listen for errors: Add an onEvent handler and check for tasks_load_failed events
  4. Network issues: Check browser console for network errors
Problem: Server-side rendering errors like “window is not defined”.Solutions:The SDK requires browser APIs and cannot run on the server. Use one of these approaches:Next.js:
Nuxt.js:
General approach:
Problem: The widget container exists but nothing renders.Solutions:
  1. Check container exists: Ensure the container element exists in the DOM before calling init()
  2. Script loaded: Verify the SDK script has loaded before initialization
  3. Console errors: Check browser console for JavaScript errors
  4. Container size: Ensure the container has dimensions (min-height, width)
Problem: Need more information about what’s happening.Solution: Enable debug logging:
This will log detailed information to the browser console about:
  • SDK initialization
  • Extension detection
  • API requests and responses
  • Event emissions
For a deeper mapping of extension/backend failures to SDK-friendly error codes, see docs/ERROR_CODES.md in the SDK repo.

Frequently Asked Questions

Yes, you have several options:
  1. Domain filtering: Set the domain parameter to show tasks for a specific domain
  2. Bounty filtering: Set the bountyId parameter to show only tasks from a specific campaign
  3. Custom task configuration: Work with our team to define custom tasks for your integration
Contact your partner manager to discuss task customization options.
Use the user parameter to identify your users:
Completions are then attributed to this user. You can access completion data through the Partner Dashboard or via webhook integrations.
Yes, you can initialize multiple widgets with different configurations:
Use ActionModel.destroyAll() to clean up all instances at once.
Yes, we provide a sandbox environment for testing integrations. Contact your partner manager to get sandbox credentials and test domains configured.
The widget itself collects minimal data:
  • Widget initialization events
  • Task interaction events (start, complete, fail)
  • User identification data you provide
The browser extension (when users complete tasks) collects path data needed to train the LAM. See our Privacy Policy for details.

Support

Documentation

Full ActionModel documentation including API reference and guides

Partner Support

Contact your partner representative for integration support

Getting Help

  • Documentation: docs.actionmodel.com
  • Partner Support: Partner onboarding team
  • Technical Issues: Include your Partner ID, domain, and browser console logs when reporting issues

ActionFi Overview

Learn about ActionFi, the bounty layer of Action Model

For Platforms

Become an ActionFi partner and get verified users

Browser Extension

Learn about the training browser extension

Ready to integrate? Contact the partner onboarding team to get your Partner ID and start embedding the widget into your platform.