@flowly/sdk v0.0.17

Flowly Attribution SDK

Flowly Attribution SDK helps you measure user acquisition, conversion events, and revenue with a privacy-first, lightweight approach. Ideal for modern web applications looking for accurate marketing attribution without sacrificing speed or user experience.

🌐 Website | 📚 Documentation

Features

• 📈 Accurate Attribution — Track page visits, events, conversions, and revenue.
• 🔒 Privacy-First — GDPR-compliant by design.
• ⚡ Lightweight & Fast — Minimal performance impact.
• 🔧 Highly Configurable — Customize logging, session management, and more.
• 🚀 Built for Developers — TypeScript support out of the box.

Installation

Install via npm or yarn:

npm install @flowly/sdk
# or
yarn add @flowly/sdk

Or use directly in the browser via CDN:

<script src="https://cdn.jsdelivr.net/npm/@flowly/sdk@latest/dist/flowly-sdk.js"></script>

Replace latest with the specific version number if needed.

When included this way, the SDK is available globally via the Flowly object.

Example:

<script src="https://cdn.jsdelivr.net/npm/@flowly/sdk@0.0.9/dist/flowly-sdk.js"></script>
<script>
  const builder = Flowly.builder();
  const flowly = builder
    .apiKey('your-api-key')
    .secret('your-secret-key')
    .productId('your-product-id')
    .productName('your-product-name')
    .build();

  flowly.pageVisit('HomePage');
</script>

Quick Start

import { builder, LogLevel } from '@flowly/sdk';

const flowly = builder()
  .apiKey('your-api-key')
  .secret('your-secret-key')
  .productId('your-product-id')
  .productName('your-product-name')
  .logLevel(LogLevel.Info)
  .sessionTimeout(1800) // Optional: Session timeout in seconds
  .consentSettings({ // Optional: Configure user consent
    isConsentGiven: true,
    analyticsEnabled: true,
    adsPersonalizationEnabled: true
  })
  .build();

// Track page visit
flowly.pageVisit('HomePage');

// Track a custom event using EventBuilder
flowly.newEvent('Signup')
  .withParameter('plan', 'Pro')
  .track();

// Track a conversion event
flowly.conversionEvent('PurchaseCompleted', { orderId: '12345' });

// Track revenue
flowly.revenue('Purchase', 'USD', 99.99, { productId: 'sku_123' });

// Identify and login a user
flowly.login('custom-user-id');

// Logout the current user
flowly.logout();

// Flush pending events
flowly.flush();

API Reference

Builder Methods

FlowlyController Methods

Utilities

LogLevel Enum

Control the verbosity of SDK logs:

LogLevel.Verbose  // Detailed logs
LogLevel.Debug    // Debugging information
LogLevel.Info     // General information
LogLevel.Warn     // Warnings
LogLevel.Error    // Errors
LogLevel.Assert   // Assertions

EventBuilder Interface

The EventBuilder provides a fluent interface to construct and send events with multiple custom parameters. You obtain an EventBuilder instance by calling newEvent(), newConversionEvent(), or newRevenueEvent() on the FlowlyController.

Example:

flowly.newEvent('PlayerUpdate')
  .withParameter('level', 5)
  .withParameter('score', 1500)
  .track();

ControllerState Enum

Represents the operational state of the Flowly SDK. Accessed via flowly.getState().

ConsentSettings Object

The ConsentSettings object allows you to specify user consent preferences. It's used with builder.consentSettings() during initialization and flowly.updateConsentSettings() at runtime.

Properties:

Example:

// To be used with builder.consentSettings() or flowly.updateConsentSettings()
const userConsent = {
  isConsentGiven: true,
  analyticsEnabled: true,
  adsPersonalizationEnabled: false // User opted out of ad personalization
};

// Example: Set initial consent during SDK build
// const flowly = builder()
//   .apiKey('your-api-key')
//   // ... other builder methods
//   .consentSettings(userConsent)
//   .build();

// Example: Update consent at runtime
// flowly.updateConsentSettings(userConsent);

(Note: The ConsentSettings object in Kotlin has static helper methods noConsent() and fullConsent(). Their availability in JS depends on JsExport of companion objects. If not directly available, create the object manually as shown above.)

AttributionData Object

Describes the resolved attribution information for the user. Accessed via flowly.getAttributionInfo().

Example:

// Structure of AttributionData object received in getAttributionInfo callback
// const attribution = {
//   network: "some_network",
//   campaign: "campaign_name",
//   attributedAt: 1678886400000, // Example timestamp
//   rawData: { custom_param: "value" }
// };

PurchaseData Object

Used with flowly.verifyPurchase() to send purchase details.

VerificationResult Object

Received in the callback from flowly.verifyPurchase().

Example

import { builder, LogLevel, isInitialized, getInstance } from '@flowly/sdk';

if (!isInitialized()) {
  builder()
    .apiKey('your-api-key')
    .secret('your-secret-key')
    .productId('your-product-id')
    .productName('your-product-name')
    .logLevel(LogLevel.Warn)
    .sessionTimeout(1800)
    .consentSettings({ // Example: Configure user consent
      isConsentGiven: true,
      analyticsEnabled: true,
      adsPersonalizationEnabled: false // User opts out of ad personalization
    })
    .build();
}

const flowlyInstance = getInstance();
flowlyInstance?.pageVisit('LandingPage');

// Example of using EventBuilder
flowlyInstance?.newEvent('NewsletterSignup')
  .withParameter('newsletter', 'TechWeekly')
  .track();

// Example of setting an event callback
flowlyInstance?.setEventSentCallback((eventName, eventType, eventArgs) => {
  console.log(`Event Sent: ${eventType} - ${eventName}`, eventArgs || {});
});

// Example of getting attribution info
flowlyInstance?.getAttributionInfo(attr => {
  if (attr) {
    console.log('Attribution:', attr.network, attr.campaign);
  } else {
    console.log('No attribution data yet.');
  }
});

Best Practices

• 🚀 Initialize Early — Initialize Flowly SDK as soon as your app loads to capture all events.
• 📖 Use Meaningful Event Names — Helps with better analytics and attribution reports.
• 🔒 Respect Privacy — Never log sensitive personal information.
• 📦 Flush Before Exit — Flush events before page unload or user logout to ensure data is sent.

License

This project is licensed under the MIT License.

Support

If you encounter any issues or have questions, please reach out:

• 📬 Contact Us