Integration Guides

Platform-specific guides for integrating Sync As A Service into your application.

Web (Vanilla JavaScript)

The simplest integration—add the SDK script and initialize.

Embed the widget directly in your page:

<!DOCTYPE html>
<html>
  <head>
    <title>My App</title>
  </head>
  <body>
    <h1>Connect Your Accounts</h1>

    <!-- Widget container -->
    <div id="sync-widget" style="min-height: 500px;"></div>

    <!-- SDK -->
    <script src="https://sync-api.stackline.com/sync-sdk/latest/sdk.umd.js"></script>
    <script>
      SyncSDK.init({
        clientId: "bc_your_app_id",
        environment: "production",
        container: document.getElementById("sync-widget"),

        onSync: (result) => {
          console.log(`Synced ${result.ordersFound} orders`);
          // Refresh your app's data
          location.reload();
        },

        onEvent: (event, metadata) => {
          console.log("Event:", event, metadata);
        },
      });
    </script>
  </body>
</html>

Open the widget as a modal when user clicks a button:

<button id="connect-btn">Connect Retailers</button>
<div id="sync-modal" style="display: none;"></div>

<script src="https://sync-api.stackline.com/sync-sdk/latest/sdk.umd.js"></script>
<script>
  document.getElementById("connect-btn").addEventListener("click", () => {
    // Show modal container
    const modal = document.getElementById("sync-modal");
    modal.style.display = "block";
    modal.style.position = "fixed";
    modal.style.top = "50%";
    modal.style.left = "50%";
    modal.style.transform = "translate(-50%, -50%)";
    modal.style.width = "400px";
    modal.style.height = "600px";
    modal.style.zIndex = "1000";
    modal.style.backgroundColor = "white";
    modal.style.borderRadius = "12px";
    modal.style.boxShadow = "0 4px 20px rgba(0,0,0,0.3)";

    // Initialize widget
    const widget = SyncSDK.init({
      clientId: "bc_your_app_id",
      environment: "production",
      container: modal,

      onSync: (result) => {
        modal.style.display = "none";
        widget.destroy();
        alert(`Connected! Found ${result.ordersFound} orders.`);
      },

      onExit: () => {
        modal.style.display = "none";
        widget.destroy();
      },
    });
  });
</script>

React / Next.js

Basic React Component

import { useEffect, useRef } from "react";

export function SyncWidget({ onComplete }) {
  const containerRef = useRef(null);
  const widgetRef = useRef(null);

  useEffect(() => {
    // Load SDK if not already loaded
    if (!window.SyncSDK) {
      const script = document.createElement("script");
      script.src = "https://sync-api.stackline.com/sync-sdk/latest/sdk.umd.js";
      script.onload = initWidget;
      document.body.appendChild(script);
    } else {
      initWidget();
    }

    function initWidget() {
      widgetRef.current = window.SyncSDK.init({
        clientId: "bc_your_app_id",
        environment:
          process.env.NODE_ENV === "production" ? "production" : "sandbox",
        container: containerRef.current,

        onSync: (result) => {
          onComplete?.(result);
        },
      });
    }

    return () => {
      widgetRef.current?.destroy();
    };
  }, [onComplete]);

  return <div ref={containerRef} style={{ minHeight: 500 }} />;
}

Usage

function AccountsPage() {
  const handleSyncComplete = (result) => {
    console.log(`Synced ${result.ordersFound} orders`);
    // Refetch orders from your API
    mutate("/api/orders");
  };

  return (
    <div>
      <h1>Connect Your Accounts</h1>
      <SyncWidget onComplete={handleSyncComplete} />
    </div>
  );
}

Next.js (App Router)

For Next.js, load the SDK client-side only:

"use client";

import dynamic from "next/dynamic";

const SyncWidget = dynamic(() => import("./SyncWidget"), {
  ssr: false, // Widget must run client-side
  loading: () => <div>Loading...</div>,
});

export default function Page() {
  return <SyncWidget onComplete={(r) => console.log(r)} />;
}

Mobile WebView

Embed the widget in a native mobile app using WebView.

iOS (Swift / WKWebView)

import WebKit

class SyncViewController: UIViewController, WKNavigationDelegate, WKScriptMessageHandler {

    var webView: WKWebView!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Configure WebView
        let config = WKWebViewConfiguration()
        config.preferences.javaScriptEnabled = true

        // Add message handler for events
        config.userContentController.add(self, name: "syncEvents")

        webView = WKWebView(frame: view.bounds, configuration: config)
        webView.navigationDelegate = self
        view.addSubview(webView)

        // Load widget HTML
        let html = """
        <!DOCTYPE html>
        <html>
        <head>
            <meta name="viewport" content="width=device-width, initial-scale=1">
            <style>
                body { margin: 0; padding: 0; }
                #widget { width: 100%; height: 100vh; }
            </style>
        </head>
        <body>
            <div id="widget"></div>
            <script src="https://sync-api.stackline.com/sync-sdk/latest/sdk.umd.js"></script>
            <script>
                SyncSDK.init({
                    clientId: "bc_your_app_id",
                    environment: "production",
                    container: document.getElementById("widget"),
                    onSync: (result) => {
                        webkit.messageHandlers.syncEvents.postMessage({
                            type: "SYNC_COMPLETE",
                            data: result
                        });
                    },
                    onExit: () => {
                        webkit.messageHandlers.syncEvents.postMessage({
                            type: "EXIT"
                        });
                    }
                });
            </script>
        </body>
        </html>
        """

        webView.loadHTMLString(html, baseURL: URL(string: "https://sync-api.stackline.com"))
    }

    // Handle messages from JavaScript
    func userContentController(_ userContentController: WKUserContentController,
                               didReceive message: WKScriptMessage) {
        guard let body = message.body as? [String: Any],
              let type = body["type"] as? String else { return }

        switch type {
        case "SYNC_COMPLETE":
            if let data = body["data"] as? [String: Any] {
                print("Synced \(data["ordersFound"] ?? 0) orders")
            }
            dismiss(animated: true)
        case "EXIT":
            dismiss(animated: true)
        default:
            break
        }
    }
}

Android (Kotlin / WebView)

class SyncActivity : AppCompatActivity() {

    private lateinit var webView: WebView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        webView = WebView(this).apply {
            settings.javaScriptEnabled = true
            settings.domStorageEnabled = true

            // Add JavaScript interface for events
            addJavascriptInterface(SyncBridge(), "Android")

            webViewClient = WebViewClient()
        }

        setContentView(webView)

        val html = """
        <!DOCTYPE html>
        <html>
        <head>
            <meta name="viewport" content="width=device-width, initial-scale=1">
            <style>
                body { margin: 0; padding: 0; }
                #widget { width: 100%; height: 100vh; }
            </style>
        </head>
        <body>
            <div id="widget"></div>
            <script src="https://sync-api.stackline.com/sync-sdk/latest/sdk.umd.js"></script>
            <script>
                SyncSDK.init({
                    clientId: "bc_your_app_id",
                    environment: "production",
                    container: document.getElementById("widget"),
                    onSync: (result) => {
                        Android.onSyncComplete(JSON.stringify(result));
                    },
                    onExit: () => {
                        Android.onExit();
                    }
                });
            </script>
        </body>
        </html>
        """.trimIndent()

        webView.loadDataWithBaseURL(
            "https://sync-api.stackline.com",
            html,
            "text/html",
            "UTF-8",
            null
        )
    }

    inner class SyncBridge {
        @JavascriptInterface
        fun onSyncComplete(resultJson: String) {
            runOnUiThread {
                val result = JSONObject(resultJson)
                Log.d("Sync", "Synced ${result.optInt("ordersFound")} orders")
                finish()
            }
        }

        @JavascriptInterface
        fun onExit() {
            runOnUiThread { finish() }
        }
    }
}

Backend-Only (Headless)

For backend integrations without the widget (e.g., data pipelines), use the REST API directly.

Prerequisites

Users must have already connected retailers via the widget in another app
You have a valid access token for the user

Fetch Orders

// Node.js example
async function fetchUserOrders(accessToken) {
  const response = await fetch("https://sync-api.stackline.com/sync/orders", {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// Usage
const orders = await fetchUserOrders(userToken);
console.log(`Found ${orders.length} order items`);

Get Connected Retailers

async function getConnections(accessToken) {
  const response = await fetch("https://sync-api.stackline.com/sync/connections", {
    headers: { Authorization: `Bearer ${accessToken}` },
  });

  return response.json();
}

Trigger Manual Sync

async function triggerSync(accessToken, retailerId) {
  const response = await fetch(
    `https://sync-api.stackline.com/sync/connections/${retailerId}/sync`,
    {
      method: "POST",
      headers: { Authorization: `Bearer ${accessToken}` },
    }
  );

  return response.json(); // Returns { syncBatchId }
}

See API Reference for complete endpoint documentation.

Environment Configuration

Environment

API URL

Widget URL

Use For

sandbox

sync-api-beta.stackline.com

Same SDK, sandbox API

Development

production

sync-api.stackline.com

Same SDK, production API

Live apps

Environment Detection

function getEnvironment() {
  // Production domains
  if (
    window.location.hostname === "yourapp.com" ||
    window.location.hostname === "www.yourapp.com"
  ) {
    return "production";
  }
  // Everything else (staging, localhost)
  return "sandbox";
}

SyncSDK.init({
  clientId: "bc_your_app_id",
  environment: getEnvironment(),
  container: document.getElementById("widget"),
});

Production Checklist

Before going live:

Switch environment from sandbox to production
Pin widgetVersion to a specific version (e.g., "v1.0.0")
Update backend API URLs from sync-api-beta.stackline.com to sync-api.stackline.com
Set up error handling with onEvent and onExit callbacks
Test with real retailer accounts (not just demo credentials)
Verify order data appears correctly in your app

Next Steps

Widget Reference - All widget states and customization options
API Reference - REST API endpoints
Data Reference - Order data structure

PreviousGetting Started NextWidget Reference

Last updated 1 hour ago

Was this helpful?

hashtagWeb (Vanilla JavaScript)

hashtagInline Widget

hashtagModal Overlay

hashtagReact / Next.js

hashtagBasic React Component

hashtagUsage

hashtagNext.js (App Router)

hashtagMobile WebView

hashtagiOS (Swift / WKWebView)

hashtagAndroid (Kotlin / WebView)

hashtagBackend-Only (Headless)

hashtagPrerequisites

hashtagFetch Orders

hashtagGet Connected Retailers

hashtagTrigger Manual Sync

hashtagEnvironment Configuration

hashtagEnvironment Detection

hashtagProduction Checklist

hashtagNext Steps