voucher_sdk #

voucher_sdk is a Flutter SDK that allows host applications to integrate and display the voucher experience. You can open the complete voucher experience or navigate directly to a specific SKU.

Features #

• Initialize the SDK with user details and client credentials.
• Open the complete voucher experience.
• Open a specific voucher using its SKU ID.
• Integrate Firebase Analytics through a custom VoucherAnalytics implementation.
• Check whether the SDK is currently open.

Getting started #

Add the SDK dependency to your application's pubspec.yaml:

dependencies:
  voucher_sdk: ^YOUR_VERSION

Replace YOUR_VERSION with the version you want to integrate.

Import the SDK using its public entry point:

import 'package:voucher_sdk/voucher_sdk.dart';

Ensure that the public import path matches your package's actual entry point.

Usage #

1. Initialize the SDK #

Initialize the SDK before opening it. Pass your navigator key, client credentials, and user details.

await VoucherSdk.initialize(
  navigatorKey: navigatorKey,
  clientId: "YOUR_CLIENT_ID",
  secret: "YOUR_CLIENT_SECRET",
  name: "John Doe",
  mobile: "9876543210",
  email: "john@example.com",
  clientConsumerId: "USER_123",
);

Initialization parameters

Initialization parameters

Note: You must provide at least one of mobile or email when initializing the SDK. Both can be provided, but neither can be omitted at the same time.

2. Open the complete voucher experience #

Call VoucherSdk.open() without parameters to open the default voucher experience.

await VoucherSdk.open();

3. Open a specific SKU #

Pass the SKU ID to open a particular voucher.

const String skuId = "YOUR_SKU_ID";

await VoucherSdk.open(sku: skuId);

The sku parameter is optional and defaults to an empty string. If omitted, the SDK opens the default voucher experience.

Analytics integration #

The Voucher SDK supports custom analytics through the VoucherAnalytics interface.

If you want to use Firebase Analytics, you must integrate and initialize Firebase in your host application. The host application must implement VoucherAnalytics and pass an instance to VoucherSdk.initialize().

1. Add Firebase dependencies #

Add Firebase Core and Firebase Analytics to your host application's pubspec.yaml:

dependencies:
  firebase_core: ^LATEST_VERSION
  firebase_analytics: ^LATEST_VERSION

Replace LATEST_VERSION with compatible versions for your project.

Configure Firebase by following the official FlutterFire setup guide.

2. Create the analytics provider #

Create a file named voucher_analytics_provider.dart in your host application.

Implement the VoucherAnalytics interface:

import 'package:firebase_analytics/firebase_analytics.dart';
import 'package:voucher_sdk/app/analytics/voucher_analytics.dart';

class VoucherAnalyticsProvider extends VoucherAnalytics {
  static FirebaseAnalytics? firebaseAnalytics;

  @override
  Future<void> logEvent({
    required String eventName,
    Map<String, Object>? parameters,
  }) async {
    await firebaseAnalytics?.logEvent(
      name: eventName,
      parameters: parameters,
    );
  }

  @override
  Future<void> logPurchase({
    Map<String, Object>? parameters,
  }) async {
    final rawItems = parameters?['items'];
    final analyticsItems = <AnalyticsEventItem>[];

    if (rawItems is List) {
      for (final item in rawItems) {
        if (item is Map) {
          analyticsItems.add(
            AnalyticsEventItem(
              itemId: item['sku']?.toString(),
              itemName: item['productName']?.toString(),
              quantity: item['quantity'] is num
                  ? (item['quantity'] as num).toInt()
                  : int.tryParse(
                      item['quantity']?.toString() ?? '',
                    ),
            ),
          );
        }
      }
    }

    await firebaseAnalytics?.logPurchase(
      items: analyticsItems,
    );
  }
}

This implementation forwards SDK analytics events to Firebase Analytics. Purchase events convert the SDK's item data into Firebase AnalyticsEventItem objects.

3. Initialize Firebase in the host application #

Initialize Firebase before initializing the Voucher SDK.

import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_analytics/firebase_analytics.dart';

import 'firebase_options.dart';
import 'voucher_analytics_provider.dart';

Future<void> initializeFirebaseAnalytics() async {
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );

  VoucherAnalyticsProvider.firebaseAnalytics =
      FirebaseAnalytics.instance;
}

Ensure firebase_options.dart is generated and configured for your host application's Firebase project. If your app already initializes Firebase, do not initialize it again unnecessarily; set the analytics instance instead.

4. Pass the analytics provider to the Voucher SDK #

After Firebase initialization, pass a VoucherAnalyticsProvider instance through the analytics parameter.

await VoucherSdk.initialize(
  navigatorKey: navigatorKey,
  clientId: "YOUR_CLIENT_ID",
  secret: "YOUR_CLIENT_SECRET",
  name: "John Doe",
  mobile: "9876543210",
  email: "john@example.com",
  clientConsumerId: "USER_123",
  analytics: VoucherAnalyticsProvider(),
);

If analytics is not required, you can omit the analytics parameter.

Important: Firebase initialization and configuration are the responsibility of the host application. The Voucher SDK does not initialize Firebase itself.

Check SDK state #

Use VoucherSdk.isOpen to check whether the SDK is currently open.

if (VoucherSdk.isOpen) {
  // The SDK is currently open.
}

The SDK prevents opening another SDK screen while one is already open.

Additional information #

• Always initialize the SDK before calling VoucherSdk.open().
• Use VoucherSdk.open() to open the default voucher experience.
• Use VoucherSdk.open(sku: skuId) to open a specific SKU.
• Ensure the supplied navigator key is attached to the host application's navigator.
• Initialize Firebase in the host application before using Firebase Analytics through the SDK.
• Pass an instance of VoucherAnalyticsProvider to the analytics parameter when analytics is required.
• Keep client credentials secure and avoid committing production secrets to source control.

For integration support or to report an issue, contact the SDK development team.