All Products
Document Center

Custom plugin

Last Updated: Feb 20, 2021

To finish some events at a specific time point, for example, to record tracking when accessing the page, you need to develop a plug-in. After subscribing to corresponding events, the plug-in can process data carried in the events in the handler.

About this task

The plug-in customization procedure covers the following steps:

  1. Create a plug-in.
  2. Register the plug-in.
  3. Use the plug-in.

This topic describes how to use a demo of H5 container and offline package to customize a plug-in that modifies the navigation bar when an H5 page is loaded.


Create a plug-in

The format of a newly created plug-in is described as follows:

  • Naming format: The name of a newly created plug-in is consistent with the default plug-in name provided by the container. The name begins with XXPlugin4, where XX is a custom prefix.
  • Base class: All plug-ins are derived from NBPluginBase by inheritance.
  • Basic methods: Rewrite the following three methods in the .m file:
    • - (void)pluginDidLoad: required. H5 events being listened to. For details about the event list, see the header file NBDefines.h.
    • - (void)handleEvent: required. Process the logic after the event being listened to is triggered.
    • - (``**int**``)``priority: required. Set the event priority to PSDPluginPriority_High`` +``1
    • - (void)addJSApis: optional. A JSAPI may need to be registered for communicating with the H5 container.

The following sample code is for your reference.

  1. #import <NebulaSDK/NBPluginBase.h>
  2. @interface MPPlugin4TitleView : NBPluginBase
  3. @end
  4. @implementation MPPlugin4TitleView
  5. - (void)pluginDidLoad
  6. {
  7. }
  8. - (void)handleEvent:(PSDEvent *)event
  9. {
  10. [super handleEvent:event];
  11. }
  12. - (int)priority
  13. {
  14. return PSDPluginPriority_High +1;
  15. }

Listen to an event

In the - (void)pluginDidLoad method, register an event to be listened to.

  1. - (void)pluginDidLoad {
  2. self.scope = kPSDScope_Scene; // 1
  3. [ addEventListener:kNBEvent_Scene_NavigationItem_Left_Back_Create_After withListener:self useCapture:NO];
  4. // -- Change the navigation bar style.
  5. [ addEventListener:kH5Event_Scene_NavigationBar_ChangeColor withListener:self useCapture:NO];
  6. [super pluginDidLoad];
  7. }

The addEventListener method is used to listen to a certain event. The following table describes the parameters.

Parameter Description
scope Impact scope of the event. Currently, supported scopes from small to large include Scene, Session, and Service.
event Event name. Event constants are defined in NBDefines.h.
listener Event handler, that is, the object that provides - handleEvent:.
capture Whether to spread the event in capture method. The value is generally set to NO.

Set the plug-in priority

Set a high plug-in priority to prevent the custom plug-in from being overridden.

  1. - (int)priority
  2. {
  3. return PSDPluginPriority_High +1;
  4. }

Handle listening

In - handleEvent:, handle the logic after the event being listened to is triggered.

  1. - (void)handleEvent:(NBNavigationTitleViewEvent *)event
  2. {
  3. [super handleEvent:event];
  4. if ([kNBEvent_Scene_NavigationItem_Left_Back_Create_After isEqualToString:event.eventType]){
  5. // Change the style based on the default back button.
  6. NSArray *leftBarButtonItems = event.context.currentViewController.navigationItem.leftBarButtonItems;
  7. if ([leftBarButtonItems count] == 1) {
  8. if (leftBarButtonItems[0] && [leftBarButtonItems[0] isKindOfClass:[AUBarButtonItem class]]) {
  9. // On the basis of the default Back button, modify the Back arrow and text color.
  10. AUBarButtonItem *backItem = leftBarButtonItems[0];
  11. backItem.backButtonColor = [UIColor greenColor];
  12. backItem.titleColor = [UIColor colorFromHexString:@"#00ff00"];
  13. // Hide the Back arrow.
  14. // backItem.hideBackButtonImage = YES;
  15. // Hide the text on the back button: Set the text to transparent while retain the clickable area of the back button.
  16. // backItem.titleColor = [UIColor clearColor];
  17. }
  18. }
  19. [event preventDefault];
  20. [event stopPropagation];
  21. }else if([kH5Event_Scene_NavigationBar_ChangeColor isEqualToString:event.eventType]) {
  22. // Prevent the default navigation bar style of the container.
  23. [event preventDefault];
  24. [event stopPropagation];
  25. }
  26. }


If a custom JSAPI is required for interaction with the H5 page during registration of a plug-in, you can register the custom JSAPI in the - (void)addJSApis method. See Customize a JSAPI > Register the JSAPI by code. This method is optional and does not need to be implemented if not required.

  1. - (void)addJSApis
  2. {
  3. [super addJSApis];
  4. // You may add custom JSAPIs related to TitleView here.
  5. }

Register the plug-in

After a plug-in class is created, you need to register the plug-in in the custom PLIST file. See Customize a JSAPI > Register JSAPI.


The registered plug-in is of the dictionary type and includes the following items.

Parameter Description
name Name of the created plug-in
scope Effective scope of the plug-in
events Name of an event being listened to

Use the plug-in

  • Add an interruption point in the pluginDidLoad method and observe whether the stack calling sequence is correct.


  • Add a breakpoint in the handleEvent method and check whether the event being listened can be correctly triggered.


  • Check whether the custom style of the navigation bar on the H5 page takes effect.