Interactions

Interactions are how the Frak SDK records what a user does in your app: arriving from a shared link, sharing a product, or a custom event you define. They are what campaigns and rewards are calculated from.

How Interactions Work

1. Automatic Tracking: The SDK tracks user arrivals, referrals, and sharing events through a simple fire-and-forget API.

2. Merchant Resolution: The SDK automatically resolves your merchant identity from your domain. No need to pass product or merchant IDs manually.

3. Offline Support: If a user isn’t logged in, interactions are stored locally in the browser and sent once a session is established, ensuring privacy and data integrity.

4. Transparent Process: The entire interaction recording process happens in the background, invisible to the user.

Interaction Types

The SDK supports three interaction types:

• arrival: track when a user lands on your site, with optional referral attribution.
• sharing: track when a user shares your content via the sharing modal.
• custom: track any custom event specific to your application.

Sending Interactions

Use the sendInteraction action to record events:

import { sendInteraction } from '@frak-labs/core-sdk/actions';

// Track a user arrival with referral attribution
await sendInteraction(client, {
    type: "arrival",
    referrerWallet: "0x1234...abcd",
});

// Track a sharing event
await sendInteraction(client, { type: "sharing" });

// Send a custom interaction
await sendInteraction(client, {
    type: "custom",
    customType: "newsletter_signup",
    data: { email: "user@example.com" },
});

sendInteraction is fire-and-forget: errors are caught and logged, not thrown.

Referral Interactions

For referral tracking, the SDK provides a dedicated helper that handles the full referral flow automatically:

import { referralInteraction } from '@frak-labs/core-sdk/actions';

const result = await referralInteraction(client, {
    options: {
        alwaysAppendUrl: true,
        merchantId: "550e8400-e29b-41d4-a716-446655440000",
    },
});

See referralInteraction for details.

Benefits of Interactions

• Engagement Tracking: Monitor user activity on your platform.
• Reward Systems: Implement campaigns that distribute rewards based on user interactions.
• Privacy-Preserving: Interactions are only sent when a user has an active session.
• Flexible Integration: Use built-in types or define custom interactions for your specific use case.

Best Practices

• Use the referralInteraction helper for referral flows instead of manually composing arrival interactions.
• Set default UTM / attribution params via the SDK attribution config to improve marketing attribution on shared links.
• Use idempotencyKey on custom interactions to prevent duplicate event recording.

For detailed parameter information, refer to the SendInteractionParamsType reference.