AdMesh Flutter UI SDK

admesh_flutter_ui_sdk is the native Flutter SDK for rendering AdMesh recommendations with built-in tracking, theming, and format-aware widgets.

Why This Package

Native Flutter widgets for tail, product_card, bridge, and sponsored follow-up recommendation flows
/aip/context integration through a typed AdMeshSdk
Provider-based session, tracker, and SDK access
Impression, click, and follow-up engagement tracking
ThemeExtension-based styling with light/dark support

Installation

dependencies:
  admesh_flutter_ui_sdk: ^0.1.0

Requirements

Flutter 3.19.0+
Dart 3.3.0+
A valid AdMesh API key

Quick Start

Direct SDK usage

import 'package:admesh_flutter_ui_sdk/admesh_flutter_ui_sdk.dart';

final sdk = AdMeshSdk(
  config: const AdMeshSdkConfig(apiKey: 'your-api-key'),
);

final sessionId = AdMeshSdk.createSession();
final messageId = AdMeshSdk.createMessageId(sessionId);

final recommendation = await sdk.showRecommendations(
  ShowRecommendationsOptions(
    query: 'best CRM for small business',
    sessionId: sessionId,
    messageId: messageId,
    platformSurface: 'mobile_chat',
    locale: 'en-US',
    geo: 'US',
  ),
);

apiBaseUrl defaults internally to https://api.useadmesh.com. Only override it for non-production environments or custom routing.

import 'package:admesh_flutter_ui_sdk/admesh_flutter_ui_sdk.dart';
import 'package:flutter/material.dart';

class AdMeshDemo extends StatelessWidget {
  const AdMeshDemo({super.key});

  @override
  Widget build(BuildContext context) {
    final sessionId = AdMeshSdk.createSession();

    return AdMeshProvider(
      config: const AdMeshSdkConfig(apiKey: 'your-api-key'),
      sessionId: sessionId,
      child: AdMeshRecommendations(
        loadRecommendation: (sdk) => sdk.showRecommendations(
          ShowRecommendationsOptions(
            query: 'best CRM for small business',
            sessionId: sessionId,
            messageId: AdMeshSdk.createMessageId(sessionId),
          ),
        ),
        onPasteToInput: (prompt) {
          // Handle bridge CTA prompt insertion.
        },
        onExecuteQuery: (query) async {
          // Handle sponsored follow-up query execution.
        },
        onOpenLink: (url) async {
          // Launch the tracked click URL.
        },
      ),
    );
  }
}

Public API

The documented beta surface for 0.1.0 is:

AdMeshSdk, AdMeshSdkConfig, ShowRecommendationsOptions
AdMeshProvider, AdMeshScope.of(context)
AdMeshRecommendations, AdMeshLayout
AdMeshEcommerceCards, AdMeshBridgeFormat, AdMeshFollowup, AdMeshBadge
AdMeshTracker, AdMeshViewabilityTracker, AdMeshLinkTracker
AdMeshThemeData

Supported Formats

Format	Purpose	Primary widget
`tail`	Summary-first recommendation panel	`AdMeshRecommendations` / `AdMeshLayout`
`product_card`	Product carousel rendering	`AdMeshEcommerceCards`
`bridge`	Prompt-paste and link-out CTA flow	`AdMeshBridgeFormat`
Sponsored follow-up	Suggested next query with tracking	`AdMeshFollowup`

AdMeshLayout chooses the widget based on backend response metadata:

product_card with products[] renders AdMeshEcommerceCards
bridge or bridge_prompt renders AdMeshBridgeFormat
other supported payloads fall back to tail-style rendering

Tracking

The package includes first-party tracking primitives:

AdMeshTracker for exposure, click, and follow-up engagement requests
AdMeshViewabilityTracker for impression firing after visibility threshold and duration
AdMeshLinkTracker for tracked click flows before opening the destination

Impression tracking defaults to the Flutter SDK’s MRC-style behavior: 50% visible for 1 second before firing exposure.

Theming

Use AdMeshThemeData as a ThemeExtension:

MaterialApp(
  theme: ThemeData(
    useMaterial3: true,
    extensions: <ThemeExtension<dynamic>>[
      AdMeshThemeData.light(),
    ],
  ),
  home: const Placeholder(),
)

You can customize accent colors, surface colors, typography, spacing, and border radius while keeping the recommendation widgets on the same theme system as the rest of your app.

Flutter-specific Limitations In 0.1.0

Native Flutter widget parity is included for tail, product_card, bridge, and sponsored follow-up flows
/aip/context integration is included
DOM-based Weave link mutation, CSS injection, and browser-specific link processing are not part of Flutter 0.1.0

Example App

The package includes an example app under example/ that shows:

static ecommerce rendering
bridge CTA prompt insertion
sponsored follow-up execution
direct SDK fetch flow

Publish Validation

Before publishing to pub.dev, run these commands from the package root:

flutter pub get
flutter analyze
flutter test
flutter pub publish --dry-run