Flutter — MoEngage Integration

Integrate MoEngage self-handled in-app campaigns into your Digia-powered Flutter app using the digia_moengage_plugin package.

digia_moengage_plugin is a Flutter plugin that bridges MoEngage self-handled in-app campaigns into Digia's rendering engine. When MoEngage triggers an in-app campaign, this plugin intercepts the payload and renders the campaign UI using your Digia Studio layout — giving you full visual control over in-app messages without writing campaign UI code.

Package: digia_moengage_plugin Version: ^1.0.0-beta.2 Platform: Android, iOS

---

How It Works

MoEngage supports a mode called Self-Handled In-App Campaigns — instead of MoEngage rendering its own UI, it delivers the campaign payload to your app. digia_moengage_plugin intercepts this payload and passes it to digia_engage, which renders the experience using the layout you designed in Digia Studio.

MoEngage Campaign Trigger
        │
        ▼
[moengage_flutter SDK]
        │  self-handled in-app callback
        ▼
[digia_moengage_plugin]
        │  maps payload → InAppPayload
        ▼
[digia_engage runtime]
        │  SHOW_BOTTOM_SHEET / SHOW_DIALOG  → DigiaHost renders overlay
        │  SHOW_INLINE                      → DigiaSlot renders inline
        ▼
Campaign UI (native Flutter widgets from Digia Studio)

---

Prerequisites

Before integrating, ensure you have:

1. MoEngage account with your project configured. See MoEngage Docs.

2. Digia Studio account with campaign pages designed. See Digia Engage — Flutter SDK.

3. moengage_flutter set up in your app. See MoEngage Flutter Integration.

---

Flutter Integration

1. Initialize Digia and Register MoEngagePlugin

import 'package:digia_engage/digia_engage.dart';
import 'package:digia_moengage_plugin/digia_moengage_plugin.dart';
import 'package:moengage_flutter/moengage_flutter.dart';
import 'package:flutter/material.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 1. Initialize MoEngage
  final _moEngage = MoEngageFlutter('YOUR_MOENGAGE_APP_ID');
  _moEngage.initialise();

  // 2. Initialize Digia CEP facade
  await Digia.initialize(DigiaConfig(
    apiKey: 'YOUR_DIGIA_CEP_API_KEY',
    environment: DigiaEnvironment.production,
  ));

  // 3. Register the MoEngage plugin with Digia
  Digia.register(MoEngagePlugin(instance: _moEngage));

  runApp(const MyApp());
}

2. Set Up DigiaHost and DigiaNavigatorObserver

Wrap your MaterialApp so that DigiaHost can present overlays (bottom sheets and dialogs) and DigiaNavigatorObserver can forward screen changes for campaign trigger rules.

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

  final _navigatorKey = GlobalKey<NavigatorState>();

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: _navigatorKey,
      navigatorObservers: [DigiaNavigatorObserver()],
      builder: (context, child) => DigiaHost(
        navigatorKey: _navigatorKey,
        child: child!,
      ),
      home: const HomeScreen(),
    );
  }
}

Important: Pass the same GlobalKey<NavigatorState> to both MaterialApp.navigatorKey and DigiaHost. DigiaHost is placed above the Navigator in the widget tree and needs the key to present dialogs and bottom sheets in the correct context.

3. Add DigiaSlot for Inline Campaigns

Place DigiaSlot widgets wherever you want inline campaign content (banners, product offer cards) to appear. The placementKey must match the placement ID set in the Digia dashboard.

// In any screen widget
Column(
  children: [
    // Inline banner at the top of the home feed
    DigiaSlot('home_hero_banner'),

    // Product offer cards in the middle of a list
    DigiaSlot(
      'product_offers',
      placeholder: const SizedBox.shrink(),
    ),
  ],
)

---

Creating Campaigns in MoEngage

In your MoEngage dashboard, create an in-app campaign and set the template type to Self Handled. In the campaign payload JSON, specify what Digia should render.

Nudges (Bottom Sheet or Dialog)

Use SHOW_BOTTOM_SHEET or SHOW_DIALOG as the type. The viewId is the slug of the Digia Studio page — copy it from the page settings in the Digia dashboard.

{
  "type": "SHOW_BOTTOM_SHEET",
  "viewId": "promo_offer_sheet"
}

{
  "type": "SHOW_DIALOG",
  "viewId": "welcome_back_dialog"
}

Inline Content (Cards & Banners)

Use SHOW_INLINE for inline slots. The placementId must match the DigiaSlot key in your Flutter code. The viewId is the slug from the Digia dashboard.

{
  "type": "SHOW_INLINE",
  "placementId": "product_offers",
  "viewId": "product_offers-3YVNuN"
}

Field	Required	Description
type	Yes	SHOW_BOTTOM_SHEET, SHOW_DIALOG, or SHOW_INLINE.
viewId	Yes	Slug of the Digia Studio page. Copy from the Digia dashboard.
placementId	Inline only	Must match the DigiaSlot placementKey in your Flutter code.

Designing Campaign Pages

1. Open Digia Studio and go to your project.

2. Create or select a page for your campaign UI.

3. Design using Studio's drag-and-drop builder.

4. Add actions (Go To Page, Open URL, Fire Event) to CTA buttons.

5. Publish the page — live immediately, no app update needed.

6. Copy the page slug from the page settings and use it as viewId in the MoEngage payload. See Finding Slugs for step-by-step instructions.

---

MoEngagePlugin Lifecycle

MoEngagePlugin implements DigiaCEPPlugin. Digia manages the full lifecycle automatically after Digia.register(...).

Method	Called By	Description
setup(delegate)	Digia.register(...)	Registers the self-handled in-app handler with MoEngage and fetches any pending campaign.
forwardScreen(name)	DigiaNavigatorObserver / Digia.setCurrentScreen	Calls setCurrentContext on MoEngage and fetches campaigns for the new screen.
notifyEvent(event, payload)	DigiaHost / DigiaSlot	Dispatches impression, dismiss, and click events back to MoEngage.
teardown()	Digia.register(newPlugin)	Removes the in-app handler and clears cached campaigns when a new plugin is registered.
healthCheck()	Diagnostics	Returns whether the plugin is healthy (delegate is set).

---

Troubleshooting

Campaign not rendering

• Verify Digia.initialize(...) completes before Digia.register(...) is called.

• Ensure the MoEngage campaign template is set to Self Handled.

• Confirm viewId in the payload matches the page slug exactly (case-sensitive).

• For inline campaigns, verify placementId matches the DigiaSlot key in your widget tree.

• Check that DigiaHost is present in MaterialApp.builder for overlay (nudge) campaigns.

iOS build errors

• Run cd ios && pod install --repo-update to resolve CocoaPods dependencies.

• Ensure moengage_flutter and digia_moengage_plugin both appear in flutter pub get output without errors.

---

Dependency Reference

Package	Version	Role
digia_engage	^1.0.0-beta.2	Digia CEP rendering engine
digia_moengage_plugin	^1.0.0-beta.2	MoEngage CEP plugin for Digia
moengage_flutter	^10.5.0	MoEngage Flutter SDK

---

Next Steps

• Digia Engage — Flutter SDK — Core Flutter SDK reference including DigiaHost, DigiaSlot, and Digia.*.

• Finding Slugs — How to copy page slugs from Digia Studio to use as viewId in campaign payloads.

• Understanding Flavors — Configure environments for production builds.

• Advanced Integration — Custom widgets, analytics, and deep customization.