Launch App message and records

Launch App library provides a way to create NFC messages capable of launching Android or iOS applications.

Overview

Launch App message contains two records: URI record and Android Launch App record. Typically, the URI record contains a Universal Link used by iOS and the Android record contains an Android package name. The Universal Link is a link associated to the application.

Implementation

The Launch App records module provides functions for creating the record, and the Launch App messages module provides functions for creating and encoding the message.

The following code snippets show how to generate a Launch App message.

  1. Define the Universal Link string, Android package name string and create a buffer for the message:

    /* Package: no.nordicsemi.android.nrftoolbox */
static const uint8_t android_pkg_name[] = {
	'n', 'o', '.', 'n', 'o', 'r', 'd', 'i', 'c', 's', 'e', 'm', 'i', '.', 'a', 'n', 'd', 'r',
	'o', 'i', 'd', '.', 'n', 'r', 'f', 't', 'o', 'o', 'l', 'b', 'o', 'x' };

/* URI nrf-toolbox://main/ */
static const uint8_t universal_link[] = {
	'n', 'r', 'f', '-', 't', 'o', 'o', 'l', 'b', 'o', 'x', ':', '/', '/', 'm', 'a', 'i', 'n',
	'/'};

  2. Create the Launch App message:

    int err;

err = nfc_launchapp_msg_encode(android_package_name,
                            sizeof(android_package_name),
                            universal_link,
                            sizeof(universal_link),
                            ndef_msg_buf,
                            &len);

if (err < 0) {
     printk("Cannot encode message!\n");
     return err;
}

    Provide the following parameters:

    • Android package name string

    • Length of Android package name string

    • Universal Link string

    • Length of the Universal Link string

    • Message buffer

    • Size of the available memory in the buffer

Supported features

The library supports encoding AAR (Android Application Record) and Universal Links into NFC message.

Library Files

Files used by the Launch App messages and records.

Launch App messages

Header file: include/nfc/ndef/launchapp_msg.h
Source file: subsys/nfc/ndef/launchapp_msg.c

Launch App records

Header file: include/nfc/ndef/launchapp_rec.h
Source file: subsys/nfc/ndef/launchapp_rec.c

Samples using the library

The NFC: Launch App sample uses this library.

API documentation

Launch App messages

group nfc_launchapp_msg

Generation of NFC NDEF messages that can be used to launch apps.

Functions

int nfc_launchapp_msg_encode(uint8_t const *android_package_name, uint32_t android_package_name_len, uint8_t const *universal_link, uint32_t universal_link_len, uint8_t *buf, size_t *len)

Function for encoding an NFC NDEF launch app message.

This function encodes an NFC NDEF message into a buffer.

Parameters

  • android_package_name – [in] Pointer to the Android package name string. If NULL, the Android Application Record will be skipped.

  • android_package_name_len – [in] Length of the Android package name.

  • universal_link – [in] Pointer to the Universal Link string. If NULL, the Universal Link Record will be skipped.

  • universal_link_len – [in] Length of the Universal Link.

  • buf – [out] Pointer to the buffer for the message.

  • len – [inout] Size of the available memory for the message as input. Size of the generated message as output.

Return values

  • 0 – if the message was successfully created.

  • -EINVAL – if both android_package_name_len and universal_link were invalid (equal to NULL).

  • -ENOMEM – if the predicted message is larger than the provided buffer space.

  • Other – codes might be returned depending on the functions nfc_ndef_msg_encode and nfc_ndef_msg_record_add

Launch App records

group nfc_launchapp_rec

Generation of NFC NDEF record descriptions that launch apps.

Defines

NFC_ANDROID_REC_TYPE_LENGTH

Size of the type field of the Android Application Record, defined in the file launchapp_rec.c. It is used in the NFC_NDEF_ANDROID_LAUNCHAPP_RECORD_DESC macro.

NFC_NDEF_ANDROID_LAUNCHAPP_RECORD_DESC_DEF(name, package_name, package_name_length)

Macro for generating a description of an NFC NDEF Android Application Record (AAR).

This macro declares and initializes an instance of an NFC NDEF record description of an Android Application Record (AAR).

Note

The record descriptor is declared as an automatic variable, which implies that the NDEF message encoding (see nfc_launchapp_msg_encode) must be done in the same variable scope.

Parameters

  • name – [in] Name for accessing the record descriptor.

  • package_name – [in] Pointer to the Android package name string.

  • package_name_length – [in] Length of the Android package name.

NFC_NDEF_ANDROID_LAUNCHAPP_RECORD_DESC(name)

Macro for accessing the NFC NDEF Android Application Record descriptor instance that was created with NFC_NDEF_ANDROID_LAUNCHAPP_RECORD_DESC_DEF.

Variables

const uint8_t ndef_android_launchapp_rec_type[15]

External reference to the type field of the NFC NDEF Android Application Record, defined in the file launchapp_rec.c. It is used in the NFC_NDEF_ANDROID_LAUNCHAPP_RECORD_DESC_DEF macro.