Documentation

SDKs & Libraries

Developer Tools

SubLoop Web SDK

A lightweight JavaScript SDK for tracking payment analytics directly in the browser.

Installation

CDN

<script src="https://cdn.getsubloop.com/js/subloop-web.min.js"></script>

NPM

npm install subloop-web

Quick Start

<!DOCTYPE html>
<html>
<head>
    <title>My App</title>
    <script src="https://cdn.getsubloop.com/js/subloop-web.min.js"></script>
</head>
<body>
    <script>
        // Initialize SubLoop
        const subloop = new SubLoopWeb('pk_your_public_key_here');

        // Track a successful payment
        subloop.trackPayment({
            customerId: 'cust_001',
            amount: 29.99,
            currency: 'USD',
            subscriptionId: 'sub_001',
            status: 'succeeded'
        });
    </script>
</body>
</html>

API Reference

Initialize

const subloop = new SubLoopWeb(publicKey, options);

Parameters:

  • publicKey (string): Your SubLoop public API key
  • options (object, optional): Configuration options

Track Payment

subloop.trackPayment(paymentData);

Parameters:

  • paymentData (object): Payment information
    • customerId (string): Unique customer identifier
    • amount (number): Payment amount
    • currency (string): Currency code (e.g., 'USD')
    • subscriptionId (string, optional): Subscription identifier
    • status (string): Payment status ('succeeded', 'failed', 'pending')
    • metadata (object, optional): Additional payment metadata

Track Event

subloop.trackEvent(eventName, eventData);

Parameters:

  • eventName (string): Event name (e.g., 'subscription_created', 'trial_started')
  • eventData (object): Event data

Examples

E-commerce Checkout

// After successful payment processing
document.getElementById('checkout-form').addEventListener('submit', async function(e) {
    e.preventDefault();

    // Process payment with your payment provider
    const paymentResult = await processPayment();

    if (paymentResult.success) {
        // Track with SubLoop
        subloop.trackPayment({
            customerId: paymentResult.customerId,
            amount: paymentResult.amount,
            currency: paymentResult.currency,
            status: 'succeeded',
            metadata: {
                orderId: paymentResult.orderId,
                paymentMethod: paymentResult.paymentMethod
            }
        });

        // Redirect to success page
        window.location.href = '/success';
    }
});

Subscription Management

// Track subscription events
function onSubscriptionCreated(subscription) {
    subloop.trackEvent('subscription_created', {
        customerId: subscription.customerId,
        subscriptionId: subscription.id,
        planId: subscription.planId,
        amount: subscription.amount,
        currency: subscription.currency
    });
}

function onTrialStarted(trial) {
    subloop.trackEvent('trial_started', {
        customerId: trial.customerId,
        subscriptionId: trial.subscriptionId,
        trialDays: trial.days
    });
}

Analytics Integration

// Get analytics data (requires authentication)
subloop.getAnalytics('overview').then(data => {
    document.getElementById('mrr').textContent = `$${data.mrr}`;
    document.getElementById('customers').textContent = data.activeCustomers;
});

Configuration

Environment Setup

// Development
const subloop = new SubLoopWeb('pk_test_...', {
    baseUrl: 'https://api-dev.getsubloop.com',
    debug: true
});

// Production
const subloop = new SubLoopWeb('pk_live_...', {
    baseUrl: 'https://api.getsubloop.com',
    debug: false
});

Error Handling

subloop.trackPayment(paymentData)
    .then(response => {
        console.log('Payment tracked successfully:', response);
    })
    .catch(error => {
        console.error('Failed to track payment:', error);
        // Handle error appropriately
    });

Security

Public vs Private Keys

  • Use public keys (pk_) for client-side tracking
  • Never expose private keys (sk_) in client-side code
  • Public keys can only track events, not access sensitive data

Data Privacy

  • Only send necessary payment data
  • Avoid sending sensitive customer information
  • Use metadata for additional context, not sensitive data

Browser Support

  • Chrome 60+
  • Firefox 55+
  • Safari 12+
  • Edge 79+

Framework Integration

React

import { useEffect } from 'react';

function PaymentSuccess({ paymentData }) {
    useEffect(() => {
        if (window.SubLoopWeb) {
            const subloop = new window.SubLoopWeb('pk_your_key');
            subloop.trackPayment(paymentData);
        }
    }, [paymentData]);

    return <div>Payment successful!</div>;
}

Vue.js

<template>
    <div>Payment processed</div>
</template>

<script>
export default {
    mounted() {
        if (window.SubLoopWeb) {
            const subloop = new window.SubLoopWeb('pk_your_key');
            subloop.trackPayment(this.paymentData);
        }
    }
}
</script>

Angular

import { Component, OnInit } from '@angular/core';

declare global {
    interface Window {
        SubLoopWeb: any;
    }
}

@Component({
    selector: 'app-payment-success',
    template: '<div>Payment successful!</div>'
})
export class PaymentSuccessComponent implements OnInit {
    ngOnInit() {
        if (window.SubLoopWeb) {
            const subloop = new window.SubLoopWeb('pk_your_key');
            subloop.trackPayment(this.paymentData);
        }
    }
}

Testing

Test Mode

// Use test keys for development
const subloop = new SubLoopWeb('pk_test_your_key', {
    debug: true
});

// Test payment tracking
subloop.trackPayment({
    customerId: 'test_customer',
    amount: 10.00,
    currency: 'USD',
    status: 'succeeded'
});

Support

License

MIT License - see LICENSE file for details.