Synchronous Settings

The base plugin protocol only supports asynchronous settings; once the plugin has fired the host has no idea when it's finished or if it's worked and all it can do is hope for the best and continue. The Tasker plugin extensions provide a mechanism for the plugin to signal when it has finished, return completion status and set local variables in the task which called the plugin.

Firstly, in the EditActivity, the plugin may optionally indicate that it wishes to run synchronously by specifying a timeout:

   if (  TaskerPlugin.Setting.hostSupportsSynchronousExecution( getIntent().getExtras() ) )
      TaskerPlugin.Setting.requestTimeoutMS( resultIntentToHost, 3000 );

Note that the host may choose to ignore the requested timeout or even run the plugin completely asynchronously. From Tasker 4.7, you can find out which timeout the host is actually applying when the action fires using the function TaskerPlugin.Setting.getTimeoutHint() in FireReceiver. That may be useful for aborting processing if it can't be completed within the timeout period.

Secondly, in the plugin FireReceiver, the plugin knows that the host is waiting for it if isOrderedBroadcast() in onReceive returns true. If so, it can set a result and/or return some variables.

   if ( isOrderedBroadcast() )  {

      setResultCode( TaskerPlugin.Setting.RESULT_CODE_OK );

      if ( TaskerPlugin.Setting.hostSupportsVariableReturn( intent.getExtras() ) ) {
         Bundle vars = new Bundle();
         vars.putString( "%pcolour", "boo" );

         TaskerPlugin.addVariableBundle( getResultExtras( true ), vars );
      }
   }          

Note that the default result is OK, you can skip setResultCode in the case where there were no problems.

If your plugin cannot complete it's processing within the onReceive() function, put this code at the end of onReceive() instead:

   if ( isOrderedBroadcast() ) 
      setResultCode( TaskerPlugin.Setting.RESULT_CODE_PENDING );

This tells the host that you will send a separate completion intent at a later time.

When you're finished processing, probably in a Service, signal finish like this:

   TaskerPlugin.Setting.signalFinish( context, fireIntentFromHost, TaskerPlugin.Setting.RESULT_CODE_OK, varsBundle );

fireIntentFromHost is the second argument in FireReceiver.onReceive(). The third argument indicates the completion status. The final argument is an optional (use null if unneeded) bundle of variable values that will be applied by the host.

Error Reporting (Tasker 4.6+)

When the response code indicates failure, it's placed in the local variable %err in the task, so that the user can take an appropriate action if they wish (the user must have configured the plugin action with Continue On Error to do that).

In addition to the built-in responses, plugins can return their own customized failure codes using any integer from Setting.RESULT_CODE_FAILED_PLUGIN_FIRST upwards.

Plugins can also optionally set a human-readable error message by including a variable with name Setting.VARNAME_ERROR_MESSAGE in the appropriate parameter of addVariableBundle and addRelevantVariableList.

The error message variable should only be set when the BroadcastReceiver response code indicates a failure.

Relevant Variables

It might be useful for the plugin to know which variables the user might want the plugin to set. The host can pass these 'relevant' variables to the plugin EditActivity. They can be retrieved by the plugin as follows (typically in onCreate()):

   if ( TaskerPlugin.hostSupportsRelevantVariables( getIntent().getExtras() ) )
      String [] passedNames = TaskerPlugin.getRelevantVariableList( getIntent().getExtras() );

It might also be useful for the host to know which variables a plugin is likely to set upon completion. Tasker, for example, can use this information to show the user a variable selection list for subsequent actions in the task.

Specify that in your EditActivity just before setResult():

   if ( TaskerPlugin.hostSupportsRelevantVariables( getIntent().getExtras() ) )
      TaskerPlugin.addRelevantVariableList( resultIntent, new String [] { 
         "%pcolour\nPet Colour\nThe colour of the pet <B>last bought</B>"
      } );

The variable specification consists of 3 parts separated by newline characters:

• the variable name
• a localized (if possible) human-readable label in plain text format
• an optional, localized (if possible) human-readable description of what the variable contains at which times etc in HTML

The variable name and label are mandatory, the description is optional.

Tasker Condition Plugin Extensions

Condition Variables

Condition plugins can stipulate variable names and values (in a Bundle) which will be visible in any tasks that run as a result of a change in plugin state.

Example code in BroadcastReceiver.onReceive():

   if ( TaskerPlugin.Condition.hostSupportsVariableReturn( intent.getExtras() ) ) {
      Bundle varsBundle = new Bundle();

         varsBundle.putString( "%colour", "red" );

      TaskerPlugin.addVariableBundle( getResultExtras( true ), varsBundle );
   }

Relevant Variables

'Relevant' variables are also supported for condition plugins. The intention is that the user should be shown in the host UI any variables which may be passed by the plugin to the host.

Tasker-Generated Apps

If the user has configured a plugin condition or action, the stored Bundle data will also be carried over to the new app.

For that reason you should store all data in the passed Bundle if possible because otherwise your plugin won't work when installed on new devices when distributed e.g. via Play Store. It's beneficial to a plugin developer to be included in user-generated apps because the child app will prompt for installation of your plugin at runtime and thus increase it's presence.

Clearly, this advice does not apply to sensitive user data such as passwords. If you need to store such data locally in your plugin application, then your plugin is not going to work when distributed as an app and the user will discover that during testing and just have to live with it.

Identifying Plugins

Using Services