Apps

The widget in an app on any of the nine platforms, loaded by its widget id.

An app loads a widget configured in the back office by its widget id and draws the finished flow. The widget's Apps channel must list the app. Every call runs on the app's own sApp connection: its app key before sign-in, the person's token after. The widget limits what the flow offers and never adds to what the app may do.

Two ways to start

• On its own: SWidget.app({ appCode, clientCode, appKey, tokenStore }) makes the sApp connection inside.
• Beside an sApp client: pass the app's existing client (SWidget.forSapp(sr)), so both share one sign-in and one token store. The examples below use this form.

The configuration

The widget reads GET /app/v1/clients/{clientCode}/swidgets/{widgetId} (GraphQL platformAppSwidget). unavailable lists the capabilities the app lacks for this widget; the widget then shows "not available" with the reason. The configuration is kept for 24 hours, so the widget draws offline.

widget_not_found (404), widget_not_enabled_for_app (403) and widget_revoked (410) end the widget; see Errors.

Platforms

Every platform raises the same events: ready, select, quoted, created, cancelled, payment, signInRequired, openUrl and error. A widget never navigates: links, files, payments and sign-in belong to the app.

The widget's page in the back office shows this code with the app code and the client code filled in.

React

// npm install @superrouteca/sapp @superrouteca/sapp-react @superrouteca/swidget-react
import { createPartnerClient } from '@superrouteca/sapp';
import { SuperrouteProvider } from '@superrouteca/sapp-react';
import { Swidget } from '@superrouteca/swidget-react';

const sr = createPartnerClient({
  appCode: 'p_acme_parcels',
  clientCode: 'k3m9q2',
  appKey: 'sp_appkey_…',   // your app's own key
  tokenStore,
});

export function Widget() {
  return (
    <SuperrouteProvider client={sr}>
      <Swidget widgetId="k2m9x7q4ab1c" onCreated={(detail) => console.log(detail)} />
    </SuperrouteProvider>
  );
}

React Native

// npm install @superrouteca/sapp @superrouteca/sapp-react-native @superrouteca/swidget-react-native
import { createPartnerClient } from '@superrouteca/sapp';
import { SuperrouteProvider, createSecureTokenStore } from '@superrouteca/sapp-react-native';
import { Swidget } from '@superrouteca/swidget-react-native';

const sr = createPartnerClient({
  appCode: 'p_acme_parcels',
  clientCode: 'k3m9q2',
  appKey: 'sp_appkey_…',   // your app's own key
  tokenStore: createSecureTokenStore(secureStorage),
});

export function Widget() {
  return (
    <SuperrouteProvider client={sr}>
      <Swidget widgetId="k2m9x7q4ab1c" onPayment={({ pay_url }) => Linking.openURL(pay_url)} />
    </SuperrouteProvider>
  );
}

Flutter

// flutter pub add sapp swidget_flutter
import 'package:sapp/sapp.dart';
import 'package:swidget_flutter/swidget_flutter.dart';

final sr = PartnerClient(
  appCode: 'p_acme_parcels',
  clientCode: 'k3m9q2',
  appKey: 'sp_appkey_…', // your app's own key
  tokenStore: SecureTokenStore(),
);

SuperrouteScope(
  client: sr,
  child: SrSwidget(widgetId: 'k2m9x7q4ab1c', onCreated: (detail) => debugPrint('$detail')),
)

SwiftUI (iOS 15+, macOS 12+)

// Package.swift: .package(url: "https://github.com/Goodneo-Solutions/swidget-releases", from: "0.2.0")
// in the target: .product(name: "SWidget", package: "swidget-releases")
import SApp
import SAppUI
import SWidget

let sr = PartnerClient(appCode: "p_acme_parcels", clientCode: "k3m9q2", appKey: "sp_appkey_…", tokenStore: KeychainTokenStore())

SuperrouteScope(client: sr) {
    SwidgetView(widgetId: "k2m9x7q4ab1c")
}

Jetpack Compose

// build.gradle.kts: implementation("ca.superroute:swidget-android:0.2.0")
val sr = PartnerClient(
    appCode = "p_acme_parcels",
    clientCode = "k3m9q2",
    appKey = "sp_appkey_…", // your app's own key
    tokenStore = KeystoreTokenStore(context),
)

SuperrouteScope(client = sr) {
    Swidget(widgetId = "k2m9x7q4ab1c")
}

WPF

// dotnet add package Superroute.SWidget.Wpf
// XAML: <sw:SwidgetControl x:Name="Widget" />
using var sr = new PartnerClient("p_acme_parcels", clientCode: "k3m9q2", appKey: "sp_appkey_…", tokenStore: new ProtectedDataTokenStore());

Widget.DataContext = new SwidgetViewModel(sr, widgetId: "k2m9x7q4ab1c");

WinForms

// dotnet add package Superroute.SWidget.WinForms
using var sr = new PartnerClient("p_acme_parcels", clientCode: "k3m9q2", appKey: "sp_appkey_…", tokenStore: new ProtectedDataTokenStore());

var widget = new SwidgetControl { Dock = DockStyle.Fill, ViewModel = new SwidgetViewModel(sr, widgetId: "k2m9x7q4ab1c") };
Controls.Add(widget);