Skip to content

Getting Started

The Intent Library communicates with an installed NIMMSTA Android app by using Android intents.

Communication

Requirements

  • NIMMSTA Android App version 6.0 or above
  • If you use NIMMSTA App 7.0.5 or older: make sure the NIMMSTA app is installed before your app, otherwise the permissions may not be set correctly

Maven Repository

Next add the NIMMSTA Maven Repository to the settings.

repositories {
  /* ... */
  google()
  mavenCentral()
  maven {
    url 'https://maven.goma-cms.org/repository/nimmsta-public-release/'
    metadataSources {
      mavenPom()
      artifact()
    }
  }
}
/* ... */

repositories {
  /* ... */
  google()
  mavenCentral()
  maven {
    url = uri("https://maven.goma-cms.org/repository/nimmsta-public-release/")
    metadataSources {
      mavenPom()
      artifact()
    }
  }
}
/* ... */

Integrate Intent Library

To get started with the NIMMSTA Intent Library, add the library as a dependency to your Android project.

implementation 'com.nimmsta:intent_library:7.0.+@aar'

Installed App Resolution

The library can resolve the installed NIMMSTA app for you. By default it tries the following package order:

  1. Preferred custom package, if configured
  2. Standard App: com.nimmsta
  3. Intent App: com.nimmsta.intent
  4. Webserver App: current builds also use com.nimmsta

If you ship a custom package, configure it before the first bind. You can pass either the full package name or a short lowercase alias such as custom.

NIMMSTAService.preferredPackageName = "custom"
// also valid:
// NIMMSTAService.preferredPackageName = "com.nimmsta.custom"

NIMMSTAService.setPreferredPackageName("custom");
// also valid:
// NIMMSTAService.setPreferredPackageName("com.nimmsta.custom");

Note

The library manifest already includes package visibility for com.nimmsta and com.nimmsta.intent. Current Webserver App builds also use com.nimmsta. If you use a custom package, add that package to your app manifest queries section as well.

Initialize Library

To initialize the communication between your app and the installed NIMMSTA app, bind to NIMMSTAIntentConnection.

private lateinit var connection: NIMMSTAIntentConnection
private lateinit var manager: NIMMSTAManager

connection = NIMMSTAIntentConnection.bindServiceToActivity(this).onComplete {
    connection = it.result
    manager = it.result.manager
}

private NIMMSTAIntentConnection connection;
private NIMMSTAManager manager;

connection = NIMMSTAIntentConnection.bindServiceToActivity(this).onComplete(task -> {
    connection = task.getResult();
    manager = connection.getManager();
    return null;
});

Remember to cancel all connection attempts and close the connection to the NIMMSTA app when your component is destroyed.

override fun onDestroy() {
  manager.cancelAllConnect()
  connection.close()
  super.onDestroy()
}

@Override
public void onDestroy() {
  manager.cancelAllConnect();
  connection.close();
  super.onDestroy();
}

Initialize Library (Application Option)

This option is useful if you want to keep the connection alive while your app is in the foreground, but automatically close it when your app goes to the background. The default disconnect delay is 1 second. You can change it via ApplicationIntentConnection.disconnectDelay.

Configure any preferred package before startObserving.

class MyApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    NIMMSTAService.preferredPackageName = "custom"
    ApplicationIntentConnection.startObserving(this)
  }
}

class MyActivity : AppCompatActivity() {
  override fun onResume() {
    super.onResume()

    ApplicationIntentConnection.onReady { manager ->
      // called once when the manager is ready
    }

    ApplicationIntentConnection.manager?.let { manager ->
      // optional direct access if already connected
    }
  }
}

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        NIMMSTAService.setPreferredPackageName("custom");
        ApplicationIntentConnection.startObserving(this);
    }
}

public class MyActivity extends AppCompatActivity {
    @Override
    protected void onResume() {
        super.onResume();

        ApplicationIntentConnection.onReady(manager -> {
            // called once when the manager is ready
            return null;
        });

        NIMMSTAManager currentManager = ApplicationIntentConnection.getManager();
        if (currentManager != null) {
            // optional direct access if already connected
        }
    }
}

Installed App Webservice

If you also want to bind to the installed app's WebService, use NIMMSTAWebServiceConnection. It uses the same package resolution order and the same custom package override.

Next Steps

To learn more about what you can do with NIMMSTAManager or NIMMSTADevice, continue with the dedicated pages.