Interactions

Interactions are the cornerstone of user engagement tracking in the Wallet SDK. They allow developers to record events based on user actions within their applications, enabling features like reward systems and engagement analytics.

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 is seamless and 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.