Stories

📘 Pre-requisite:

Ensure the basic integration of the Nudge Core SDK is complete. If not, check here.

Overview

The nudge_flutter_stories package lets you add interactive stories to your app. It includes the NudgeStories and NudgeStoriesUi widgets for displaying and customizing stories. Install this plugin to launch stories from the dashboard and increase user engagement.

Installation

Add nudge_flutter_stories to your pubspec.yaml file:

dependencies:
  nudge_flutter_stories: ^latest_version

Run the following command to fetch the package:

flutter pub get

Step-by-Step Guide

Step 1 : Import the required classes.

Import the NudgeStoriesUiclass and NudgeStories widget from the nudge_flutter_stories package:

import 'package:nudge_flutter_stories/features/Stories/presentation/pages/stories_ui.dart';
import 'package:nudge_flutter_stories/nudge_stories.dart';

Step 2: Initialize and add to NudgeProvider

Create an instance of the NudgeStoriesUi class :

 final stories = NudgeStoriesUi();

Add this instance to the plugins list in the NudgeProvider

return NudgeProvider(
      nudgeInstance: core,
   	  plugins : [stories]
      child: MaterialApp(
        navigatorKey: NudgeProviderState.navigatorKey,
        navigatorObservers : [_trackerObserver],
        title: 'Flutter Demo',
        theme: ThemeData(
          primarySwatch: Colors.blue,
        ),
        home: Home(),
      ),
    );

Step 3: Add NudgeStories Widget

Place the NudgeStories widget in your app where you want to display stories, and call the track function for the event using the track method provided by the nudge_core package:

 Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const NudgeStories(),
            ElevatedButton(
              onPressed: () async {
                nudge.track(type: "TRIGGER_TYPE");
              },
              child: const Text(
                'Get Stories',
                style: TextStyle(fontSize: 20),
              ),
            ),
          ],
        ),
      ),
    );
  }

Example

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:nudge_core/nudge_core.dart';
import 'package:nudge_core/nudge_labels_manager/NudgeTrackerObserver.dart';
import 'package:nudge_core/nudge_provider.dart';
import 'package:nudge_flutter_stories/features/Stories/presentation/pages/stories_ui.dart';
import 'package:nudge_flutter_stories/nudge_stories.dart';

void main() {
  runApp(
    MainApp(),
  );
}

String apiKey = 'API_KEY';

Nudge nudge = Nudge(
  apiKey: apiKey,
);

String token = "UNINITIALIZED";
String nudgeId = "UNINITIALIZED";

class MainApp extends StatelessWidget {
  MainApp({super.key});

  final NudgeTrackerObserver _trackerObserver = NudgeTrackerObserver();

  @override
  Widget build(BuildContext context) {
    SystemChrome.setPreferredOrientations([
      DeviceOrientation.portraitUp,
    ]);
    nudge.initSession(externalId: "EXTERNAL_ID");
    
    final stories = NudgeStoriesUi();

    return NudgeProvider(
      nudgeInstance: nudge,
      plugins: [
      	stories,
      ],
      child: NudgeStoriesProvider(
        child: MaterialApp(
          theme: ThemeData(
            primarySwatch: Colors.blue,
            useMaterial3: true,
          ),
          routes: {
            "/": (context) => const HomeScreen(),
          },
          navigatorKey: NudgeProviderState.navigatorKey,
          navigatorObservers: [_trackerObserver],
        ),
      ),
    );
  }
}

class HomeScreen extends StatefulWidget {
  const HomeScreen({super.key});

  @override
  _HomeScreenState createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  @override
  void initState() {
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const NudgeStories(),
            ElevatedButton(
              onPressed: () async {
                nudge.track(type: "TRIGGER_TYPE");
              },
              child: const Text(
                'Get Stories',
                style: TextStyle(fontSize: 20),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

Stories UI Customizations

This section outlines the customizations available for the Stories.

NudgeStories(
  
   // Sizing and Layout
  trayHeight: 200, // Set the height of the entire story bar
  trayItemWidth: 100, //The width for all story thumbnails 
  trayItemHeight: 100 //The height of all story thumbnails
  trayItemRoundness : 10 // Set the roundness of the thumbnail
  
  //Layout
  horizontalEdgePadding: 10, // Set horizontal edge padding of the entire story bar
  verticalEdgePadding: 10, // Set vertical edge padding of the entire story bar
  itemSpacing: 10, // Set the spacing between individual story thumbnails
  trayVerticalAlignment: TrayAlignment.top  // Set the vertical alignment of the tray
  trayItemContentGap:10, // Set the gap between the thumbnail and the text for every story
  trayItemMargin: EdgeInsets.all(0) // Set the margin around every story thumbnail
  
  //Text customizations
  fontFamily: 'Abel', // Set the font family for the title and subtitle
  showText: true, // Show or hide text for all story thumbnails
  headingLightModeColor: Colors.black, // Set heading color for all story thumbnails in light mode
  headingDarkModeColor: Colors.white, // Set heading color for all story thumbnails in dark mode
  subheadingDarkModeColor: Colors.red, // Set subheading color for all story thumbnails in dark mode
  subheadingLightModeColor: Colors.blue, // Set subheading color for all story thumbnails light mode
  
  
  //Colors
  skeletonColor: Colors.grey, // Set the color for the skeleton of every single story thumbnail
  gradientColors: const [
    Colors.red,
    Colors.green,
    Colors.blue,
    Colors.yellow,
  ], // Apply gradient colors to all the story thumbnails
  theme: ThemeData(
    primaryColor: Colors.orangeAccent,
    fontFamily: 'Dosis',
  ), // Customize the theme
  
 
  
  children: [...], // Any list of widgets
),

Working with List View builder

NudgeStories (
children : [
   ListView.builder(
      scrollDirection: Axis.horizontal,
      itemBuilder: (context, index) {
        return Container(
          margin: const EdgeInsets.only(right: 10),
          height: 100,
          width: 100,
          color: Colors.grey,
        );
      },
      itemCount: 5,
      shrinkWrap: true, // Important, this makes the list view builder take the space that it needs
    ),]
)

Handling multiple scrollable widgets

Incase you plan to add our story widget along with an existing scrollable widget, you refer to the below snippet to handle the scroll across both widgets seamlessly.

const NudgeStories(
  customContent: [YourWidget1(...), YourWidget2(...), ...] // @type: List<Widget>
),

That's it!