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
Add the Container
Create a
div element where you want the widget to appear. Give it enough height for the task list.2
Load the SDK
Add the SDK script to your page. It exposes the global
ActionModel object.3
Initialize the Widget
Call
ActionModel.init() with your Partner ID to render the widget.Complete Quick Start Example
Installation
- Script Tag (Recommended)
- npm (Coming Soon)
CDN Installation
The simplest way to add the SDK is via our CDN. Add this script tag to your HTML:ActionModel object on window that you can use to initialize widgets.Best Practice: Place the script tag at the end of your
<body> or use the defer attribute to ensure the DOM is ready before initialization.Configuration Options
TheActionModel.init() function accepts a configuration object with the following options:
Required Options
| Option | Type | Description |
|---|---|---|
container | string | HTMLElement | CSS selector (e.g., '#widget') or DOM element reference |
partnerId | string | Your Partner Integration UUID |
Optional Options
| Option | Type | Default | Description |
|---|---|---|---|
domain | string | window.location.hostname | Domain to load tasks for |
bountyId | string | — | Filter tasks to a specific bounty campaign |
user | ExternalUserData | — | Identify your user for task attribution |
theme | WidgetTheme | Dark theme | Customize widget appearance |
onEvent | function | — | Callback for widget events |
Basic Configuration Example
Basic Configuration Example
Minimal configuration with just the required options:
Full Configuration Example
Full Configuration Example
Complete configuration using all available options:
Domain Filtering
Domain Filtering
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
Bounty Filtering
Bounty Filtering
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, here are the complete type definitions for the SDK:View TypeScript Interfaces
View TypeScript Interfaces
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.User Object Properties
| Property | Type | Required | Description |
|---|---|---|---|
externalId | string | Yes | Your internal user ID (must be unique per user) |
email | string | No | User’s email address |
metadata | object | No | Additional user attributes for analytics |
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 SDK supports comprehensive theming including colors, typography, and border radius.- Color Options
- Typography & Spacing
- Light Theme Preset
- Dark Theme Preset
Available Color Properties
| Property | Description | Default |
|---|---|---|
primary | Primary brand color (buttons, links, accents) | #9000ff |
primaryHover | Hover state for primary elements | #7406c3 |
background | Widget background | #1a1a1a |
surface | Card/surface background | #292929 |
border | Border color | #3d3d3d |
text | Primary text color | #ffffff |
textSecondary | Secondary text color | #bdbdbd |
textLight | Light text color | #dcdcdc |
textMuted | Muted text (timestamps, hints) | #7c7c7c |
success | Success state color | #4ade80 |
warning | Warning state color | #f97316 |
error | Error state color | #ef4444 |
Custom Brand Example
Match the widget to a custom brand:Events
Subscribe to widget events for analytics, custom behavior, or debugging.Event Handler Setup
Event Types Reference
| Event | Description | Additional Properties |
|---|---|---|
widget_initialized | Widget has been initialized and is ready | partnerId, domain |
extension_discovered | Browser extension found and validated | partnerId, domain |
extension_unavailable | Extension not installed or not detected | partnerId, domain |
tasks_loaded | Tasks successfully loaded from server | partnerId, domain, taskCount |
tasks_load_failed | Failed to load tasks (network error, etc.) | partnerId, domain, error |
training_started | User started a training task | partnerId, domain, taskId |
training_failed | Training failed to start | partnerId, domain, taskId, error |
Event Handling Examples
Analytics Integration
Analytics Integration
Send events to your analytics platform:
Extension Install Prompt
Extension Install Prompt
Show a custom prompt when the extension isn’t installed:
Error Handling
Error Handling
Handle errors gracefully:
Task Completion Tracking
Task Completion Tracking
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.
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 [email protected] to discuss webhook integration for your platform.Instance Methods
Theinit() 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
- Next.js
- Vue 3
- Angular
Requirements
Before integrating the Partner SDK, ensure you have:Partner Integration
Partner ID RequiredYour
partnerId must be configured in the ActionModel system. Contact [email protected] 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:| Browser | Supported | Notes |
|---|---|---|
| Chrome | ✅ | Full support |
| Edge | ✅ | Chromium-based |
| Brave | ✅ | Chromium-based |
| Opera | ✅ | Chromium-based |
| Firefox | ⏳ | Coming soon |
| Safari | ⏳ | Coming soon |
Troubleshooting
Widget shows 'Extension Not Found'
Widget shows 'Extension Not Found'
Problem: The widget displays a message that the extension is not found.Solutions:
- Ensure extension is installed: Users must install the ActionModel browser extension from the Chrome Web Store
- Check browser compatibility: The extension supports Chrome, Edge, Brave, and other Chromium browsers
-
Verify extension is enabled: Check
chrome://extensionsto ensure it’s not disabled -
Try refreshing: Sometimes the extension takes a moment to register. Call
widget.refresh()or reload the page
Widget shows 'Access Denied'
Widget shows 'Access Denied'
Problem: The widget shows an access denied error.Solutions:
- Verify your partnerId: Ensure the Partner ID is correct and matches what was provided
- Check domain whitelisting: Your domain must be allowed in your partner configuration
- Confirm partner status: Ensure your partner integration is active and enabled
- Contact support: Email [email protected] with your Partner ID and domain
No tasks appear in the widget
No tasks appear in the widget
Problem: The widget loads but shows no tasks.Solutions:
-
Verify domain configuration: Ensure tasks are configured for your domain or the specified
domainparameter - Check bountyId: If filtering by bounty, verify the bounty ID is correct
-
Listen for errors: Add an
onEventhandler and check fortasks_load_failedevents - Network issues: Check browser console for network errors
SSR Errors (Next.js, Nuxt, etc.)
SSR Errors (Next.js, Nuxt, etc.)
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:
Widget not rendering
Widget not rendering
Problem: The widget container exists but nothing renders.Solutions:
-
Check container exists: Ensure the container element exists in the DOM before calling
init() - Script loaded: Verify the SDK script has loaded before initialization
- Console errors: Check browser console for JavaScript errors
- Container size: Ensure the container has dimensions (min-height, width)
Enable Debug Mode
Enable Debug Mode
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
Frequently Asked Questions
Can I customize which tasks appear?
Can I customize which tasks appear?
Yes, you have several options:
- Domain filtering: Set the
domainparameter to show tasks for a specific domain - Bounty filtering: Set the
bountyIdparameter to show only tasks from a specific campaign - Custom task configuration: Work with our team to define custom tasks for your integration
How do I track user completions?
How do I track user completions?
Use the Completions are then attributed to this user. You can access completion data through the Partner Dashboard or via webhook integrations.
user parameter to identify your users:Can I use multiple widgets on one page?
Can I use multiple widgets on one page?
Yes, you can initialize multiple widgets with different configurations:Use
ActionModel.destroyAll() to clean up all instances at once.Is there a sandbox/test environment?
Is there a sandbox/test environment?
Yes, we provide a sandbox environment for testing integrations. Contact your partner manager to get sandbox credentials and test domains configured.
What data is collected?
What data is collected?
The widget itself collects minimal data:
- Widget initialization events
- Task interaction events (start, complete, fail)
- User identification data you provide
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: [email protected]
- Technical Issues: Include your Partner ID, domain, and browser console logs when reporting issues
Related Resources
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 [email protected] to get your Partner ID and start embedding ActionFi into your platform.