Skip to main content

Looking for React?

Use the React frontend SDK guide for admesh-ui-sdk, AdMeshProvider, AdMeshRecommendations, and WeaveAdFormatContainer.

​
Quick Start

Get started with AdMesh in 3 simple steps:
1

Add the Package

dependencies:
  admesh_flutter_ui_sdk:
    path: ../admesh-flutter-ui-sdk
2

Create an SDK Instance

import 'package:admesh_flutter_ui_sdk/admesh_flutter_ui_sdk.dart';

final sdk = AdMeshSdk(
  config: const AdMeshSdkConfig(apiKey: 'your-api-key'),
);
Your application owns session and message lifecycle. The SDK validates these values but does not persist them for you.
3

Choose Your Integration Pattern

Direct fetch
final recommendation = await sdk.showRecommendations(
  ShowRecommendationsOptions(
    query: 'best CRM for small business',
    sessionId: sessionId,
    messageId: messageId,
  ),
);
Provider + widget integration
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),
      ),
    ),
  ),
)

​
Core Concepts

​
Session Management

AdMesh uses sessions to tie recommendation exposures, clicks, and follow-up engagement to a single conversation.
  • Session ID: unique identifier for a conversation or recommendation thread
  • Message ID: unique identifier for the specific user query or turn
Your Flutter app is responsible for storing and reusing sessionId values between screens or app launches when needed.

​
Supported Formats

The Flutter SDK currently supports these native rendering paths:
FormatUse CaseWidget
TailSummary-first recommendation panelAdMeshRecommendations / AdMeshLayout
Product CardHorizontal product carouselAdMeshEcommerceCards
BridgePrompt-paste CTA and link-out flowAdMeshBridgeFormat
Sponsored Follow-upSuggested follow-up query with trackingAdMeshFollowup
Flutter v1 does not implement DOM mutation, CSS injection, or browser-specific Weave link scanning. If your backend returns structured recommendation data, render it with the Flutter widgets instead of expecting web-style inline link processing.

​
Core APIs

​
AdMeshSdk

AdMeshSdk builds the /aip/context request payload, validates required identifiers, and returns parsed recommendation data. 
final sdk = AdMeshSdk(
  config: const AdMeshSdkConfig(
    apiKey: 'your-api-key',
  ),
);

final recommendation = await sdk.fetchRecommendationFromAipContext(
  ShowRecommendationsOptions(
    query: 'best CRM for small business',
    sessionId: sessionId,
    messageId: messageId,
    platformSurface: 'mobile_chat',
    locale: 'en-US',
    geo: 'US',
    userId: 'hashed-user-id',
  ),
);
Public types 
AdMeshSdk
AdMeshSdkConfig
ShowRecommendationsOptions

​
AdMeshProvider and AdMeshScope

Use AdMeshProvider to inject the SDK, tracker, session state, optional theme, and conversation metadata into the widget tree. 
AdMeshProvider(
  config: const AdMeshSdkConfig(apiKey: 'your-api-key'),
  sessionId: sessionId,
  language: 'en-US',
  geoCountry: 'US',
  child: const MyScreen(),
)
Access the active controller from descendant widgets: 
final controller = AdMeshScope.of(context);
final sdk = controller.sdk;
final tracker = controller.tracker;
final processed = controller.processedMessageIds;

​
Recommendation Widgets

​
AdMeshRecommendations

AdMeshRecommendations is the main high-level widget. It accepts either pre-fetched recommendation data or an async loader that calls the SDK. 
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 execution
  },
  onOpenLink: (url) async {
    // Route tracked click URLs through your link handler
  },
)

​
AdMeshLayout

AdMeshLayout selects the correct native widget based on backend format metadata:
  • product_card with products[] renders AdMeshEcommerceCards
  • bridge or bridge_prompt renders AdMeshBridgeFormat
  • everything else falls back to the tail-style recommendation layout
AdMeshLayout(
  recommendation: recommendation,
  tracker: controller.tracker,
  sessionId: controller.sessionId,
)

​
Format-specific Widgets

Use these directly when you want tighter control over your UI composition: 
AdMeshEcommerceCards(...)
AdMeshBridgeFormat(...)
AdMeshFollowup(...)
AdMeshBadge(...)
AdMeshFollowup only renders when the recommendation includes:
  • followup_query
  • followup_engagement_url
  • followup_exposure_url

​
Tracking

The Flutter SDK includes the same core tracking primitives as the React SDK, adapted to native widget composition.

​
AdMeshTracker

AdMeshTracker handles:
  • exposure deduplication by sessionId + recommendationId
  • click tracking
  • follow-up exposure tracking
  • follow-up engagement tracking
final tracker = AdMeshTracker();

await tracker.fireExposure(exposureUrl, recommendationId, sessionId);
await tracker.fireClick(clickUrl, recommendationId, sessionId);
await tracker.fireFollowupEngagement(
  followupEngagementUrl,
  recommendationId,
  sessionId,
);

​
AdMeshViewabilityTracker

Wrap recommendation widgets with AdMeshViewabilityTracker to fire impressions after the recommendation is at least 50% visible for 1 second. 
AdMeshViewabilityTracker(
  tracker: controller.tracker,
  exposureUrl: recommendation.exposureUrl,
  recommendationId: recommendation.recommendationId,
  sessionId: controller.sessionId,
  child: YourRecommendationWidget(),
)

​
AdMeshLinkTracker

Use AdMeshLinkTracker around tap targets that should fire tracked click URLs before opening a destination. 
AdMeshLinkTracker(
  tracker: controller.tracker,
  clickUrl: recommendation.clickUrl,
  recommendationId: recommendation.recommendationId,
  sessionId: controller.sessionId,
  onOpenLink: (url) async {
    // launchUrl(...) or custom router
  },
  child: const Text('Learn more'),
)

​
Theming

Use AdMeshThemeData as a ThemeExtension to style recommendation surfaces consistently across your app. 
MaterialApp(
  theme: ThemeData(
    useMaterial3: true,
    extensions: <ThemeExtension<dynamic>>[
      AdMeshThemeData.light(),
    ],
  ),
  home: ...,
)
Customize colors, typography, spacing, and border radius: 
const AdMeshThemeData(
  mode: Brightness.light,
  accentColor: Color(0xFF24A0ED),
  borderRadius: 20,
)
The main theme type exposed by the package is: 
AdMeshThemeData

​
Requirements

  • Flutter 3.19.0+
  • Dart 3.3.0+
  • A valid AdMesh API key
  • Your app must provide and manage sessionId and messageId
Package dependencies used by the SDK:
  • http
  • provider
  • visibility_detector

​
Troubleshooting

AdMeshSdk requires both values for every recommendation request. Generate them with AdMeshSdk.createSession() and AdMeshSdk.createMessageId(sessionId) and store the session ID in your app state.
Check that your loader returns a real recommendation object and that the backend response includes a supported format. AdMeshRecommendations shows nothing when there is no recommendation data.
Bridge UI needs preferred_format: bridge or bridge_prompt / bridge_content. Sponsored follow-ups only render when followup_query, followup_engagement_url, and followup_exposure_url are all present.
Flutter v1 does not support DOM-based Weave link detection or mutation. Render structured recommendation payloads with AdMeshLayout or AdMeshRecommendations instead.

React Frontend SDK

Use the React SDK for web-based recommendation rendering and browser-specific Weave flows.

Platforms Overview

Compare integration approaches and format options across AdMesh platform surfaces.