Overview:

The notify verb is a powerful method to send an encrypted data transmission to an @ sign’s secondary server, in this part of, “The Power Behind Sharing Data on the atPlatform”, we’ll be deep diving into just how the notify verb works and how to implement it into your own Flutter application.

What is the Notify Verb?

The notify verb is used to send data from one atSign’s secondary server to another atSign’s secondary server securely. It is a back-end developed verb that already exists so you as the developer do not have to worry about building it yourself! What this means is that all you have to do is choose what information you’d like to send to another atSign’s secondary server, pass this information through the parameters of the verb, and the atPlatform will take care of the messy parts, such as encrypting, transmitting and other headaches!

The Arguments of the Notify Verb

The verb itself can be seen with three main parameters; AtKey atKey, String value, and OperationEnum operation. The AtKey atKey is an object that contains the following member variables (or fields):

class AtKey {
// This is where the at_key itself will be stored
String key; 
// The @sign in which the information is
//  being passed to (can even be from yourself)
String sharedWith;
// The @sign in which the information
// is being passed from
String sharedBy;
// The namespace being the name of the 
// application where the information sent originates
String namespace;
// The metadata of the AtKey itself described 
// in another article
Metadata metadata;
// This boolean variable has not actually been 
// implemented from our backend just yet so stick around for updates!
bool isRef = false;

The String variable named value is actually the AtKey object being converged as a string, more on this later. Finally, we have our OperationEnum operation which is a very important part of the notify verb as this is the deciding factor of what type of notification will be sent to the chosen secondary server. You will see that the OperationEnum is defined as an enum (which is, in its simplest terms, a nice collection of constants) and in our case, the constants are; update, delete, append, and remove. What do these all mean, however?

When OperationEnum.update is passed through notify, the atSign who is receiving the notification will cache the value sent in either an already pre-existing version of the key and update the value with the new value sent, or create an entirely new key to store the value in. When OperationEnum.delete is passed through notify, the secondary server that has received the notification will then begin the process of deleting the cached key that was previously sent to them. Both the append and remove attributes have not yet been implemented by our backend team members, however, their functionality is still quite self-explanatory. OperationEnum.append will simply append the value to an already cached key and OperationEnum.remove will remove the specified value from an already cached key. Continue staying up-to-date with the atPlatform to see when append and remove have been implemented!

Now that all of the mandatory arguments have been discussed, when an atPlatform developer takes a closer look, they will notice that the notify verb also contains five other optional arguments! These arguments are; MessageTypeEnum messageType, PriorityEnum priority, StrategyEnum strategy, int latestN, and String notifier = SYSTEM. I won’t go into deep detail as to what these all are as some of them are quite complex, especially for a beginner developer. Regardless of the complexity of these arguments, we still endorse the brave-hearted to play around with them!

Implementing the Notify Verb in your Application

Now that you have a foundational understanding of what the notify verb is and what it is doing, it is time to start using it yourself! The notify verb is succinctly utilized in Atsign’s at_cookbook demo app and will be the main source of examples for this portion of the article. To give a summary of what the at_cookbook demo application is doing, it allows a testable atSign to create a cooking recipe with a recipe name, description, list of ingredients, and a picture. After doing this, the atSign is capable of sharing this entire recipe with another testable atSign. How did we do it? First, we created a dishWidget class that in itself would be an individual recipe with each instance. What we did was first initiate the fields:

// As you can see below, we have the recipe name,
// the ingredients, a description, the image and 
// a location for which screen was previously accessed 
// by the @sign within the app. 
  final String title;
  final String ingredients;
  final String description;
  final String imageURL;
  final String prevScreen;

// We didn’t want the @sign to be capable of passing any 
// of the recipe fields as blank
// [because who doesn’t want the full scoop  of the recipe!] 
// (no pun intended)
// So we made sure to list each field as required
  DishWidget({
    @required this.title,
    @required this.ingredients,
    @required this.description,
    @required this.imageURL,
    @required this.prevScreen,
  });

After retrieving all of these fields, we then push the entire dish widget as an object to the home screen where the list of recipes is located. Now that you have the recipe itself, you’re able to pass this through the notify verb. When an atSign wishes to share a recipe, all they have to do is press a button. On press of this button, a function titled _share is then called. This function is structured as so:

// Here, we’re initializing a variable called lookup as an AtKey object
// lookup will be our recipe
AtKey lookup = AtKey()

// You’ll notice that we’re defining a couple of the attributes of 
// the AtKey object, mainly the name of the recipe
    ..key = widget.dishWidget.title
//  What @sign is this recipe being shared with?
    ..sharedWith = atSign;

// Of course, we want to ‘get’ the values of our recipe, 
// so we use the get verb which exists in the 
// serverDemoService file of the application
String value = await _serverDemoService.get(lookup);

// ttr (Time To Refresh) being called with a value of -1 
// means that we’re confident that the values
// of our recipe won’t be changing, so once the recipe has been 
// cached on the secondary server that has received the recipe, 
// it will not need to worry about updating the values at any point
// The many fascinating attributes of MetaData will be covered 
// in an article part of this series later down the road!
var metadata = Metadata()..ttr = -1;
// After passing all of the necessary values such as the metadata,
// the appropriate @ signs and the type of notification we’d like
//  to send, we simply pass the values through the notify verb!
      AtKey atKey = AtKey()
        ..key = widget.dishWidget.title
        ..metadata = metadata
        ..sharedBy = atSign
        ..sharedWith = _otherAtSign;

      var operation = OperationEnum.update;
      await _serverDemoService.notify(atKey, value, operation);

If you would like to have a walkthrough on how we developed the at_cookbook demo app, feel free to watch Tyler Time Episode 3 on YouTube! If you have any questions, be sure to ask us on Discord!