Tags

Tags let you segment content on the fly. When tags are set, the SDK only shows stories, in-app messages, onboardings, and banners whose targeting matches the current tags.

Pay attention

There are several limitations on the list of tags that can be passed to the InAppStory SDK:

1. Allowed characters: tags can only contain letters, digits, underscores (_), and dashes (-);
2. Maximum size: the final comma-separated string, when URL-encoded, must not exceed 3999 bytes.

If invalid tags are passed, a warning is logged to the console (InAppStory.tags) and the invalid tags are dropped gracefully rather than throwing an exception.

Setting tags at initialization

You can specify initial tags when initializing the plugin using InAppStoryPlugin().initWith:

Future<void> initSDK() async {
  await InAppStoryPlugin().initWith(
    '<your-api-key>',
    '<user-id>',
    tags: ['tag1', 'tag2'],
  );
}

note

If invalid tags are passed during initialization, they will be dropped and initialization will proceed with no tags.

Managing tags at runtime

You can update, add, or remove tags dynamically via InAppStoryManager.instance.

Replacing tags

Use setTags to completely replace the active tag list:

Future<void> replaceTags(List<String> tags) async {
  final bool success = await InAppStoryManager.instance.setTags(tags);
  if (!success) {
    print('Tags were invalid and cleared');
  }
}

• Returns true if the tags are valid and applied.
• If invalid tags are passed, tags are cleared (set empty) and false is returned.

Adding tags

Use addTags to append new tags to the existing list:

Future<void> addTags(List<String> tags) async {
  final bool success = await InAppStoryManager.instance.addTags(tags);
  if (!success) {
    print('Tags were invalid; nothing added');
  }
}

• Returns true if the tags are valid and added.
• If invalid tags are passed, nothing is added and false is returned.

Removing tags

Use removeTags to remove specific tags from the active list:

Future<void> removeTags(List<String> tags) async {
  final bool success = await InAppStoryManager.instance.removeTags(tags);
  if (!success) {
    print('Tags were invalid; nothing removed');
  }
}

• Returns true if the tags are valid and removed.
• If invalid tags are passed, nothing is removed and false is returned.

Setting tags with user settings

You can also pass tags together with other user properties (such as user ID, sign, locale, and placeholders) using setUserSettings:

Future<void> changeUserSettings(String newUserId,
    String newSign,
    Locale newLocale,
    List<String> newTags,
    Map<String, String> newPlaceholders,) async {
  await InAppStoryManager.instance.setUserSettings(
    userId: newUserId,
    userSign: newSign,
    locale: newLocale,
    tags: newTags,
    placeholders: newPlaceholders,
  );
}

Overriding tags in Onboardings

When showing onboarding stories, you can override tags for the specific request:

void showOnboardingWithTags(List<String> tags) {
  InAppStoryManager.instance.showOnboarding(
    10, // limit
    tags: tags,
  );
}

Reloading feed after updating tags

If the stories list was already loaded before updating tags, reload the feed using FeedStoriesController so the new tags take effect:

final feedStoriesController = FeedStoriesController();

Future<void> updateTagsAndReload(List<String> tags) async {
  await InAppStoryManager.instance.setTags(tags);
  await feedStoriesController.fetchFeedStories();
}