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.2.0

Requirements

Flutter 3.19.0+
Dart 3.3.0+
A valid AdMesh API key

Latest Schema Only

Version 0.2.0 is aligned to the latest AdMesh schema only.

AdMeshSdk.showRecommendations() returns PlatformResponse
widgets render directly from PlatformResponse
no legacy flattened recommendation payloads are supported
no prompt-paste bridge fallback is included

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 response = await sdk.showRecommendations(
  ShowRecommendationsOptions(
    query: 'best CRM for small business',
    sessionId: sessionId,
    messageId: messageId,
    platformSurface: 'mobile_chat',
    locale: 'en-US',
    geo: 'US',
  ),
);

final title = response.title;
final destinationUrl = response.destinationUrl;

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),
          ),
        ),
        onExecuteQuery: (query) async {
          // Handle sponsored follow-up query execution.
        },
        onOpenLink: (url) async {
          // Open the destination URL after tracking fires.
        },
      ),
    );
  }
}

Public API

The documented surface for 0.2.0 is:

AdMeshSdk, AdMeshSdkConfig, ShowRecommendationsOptions
PlatformResponse, PlatformRecommendation, PlatformCreative, PlatformTracking, Delegation, Product
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`	Link-out CTA rendering	`AdMeshBridgeFormat`
Sponsored follow-up	Suggested next query with tracking	`AdMeshFollowup`

AdMeshLayout chooses the widget based on backend response metadata:

product_card with recommendation.creative.products[] renders AdMeshEcommerceCards
bridge renders AdMeshBridgeFormat
other generated responses render the tail-style layout

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 firing click tracking before opening the destination URL

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

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 the Flutter SDK

Example App

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

static ecommerce rendering
bridge rendering using the latest schema
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 analyze example
flutter pub publish --dry-run