Use a license in your app

Production licenses can be applied in one of two ways:

• Using a license string A license string is a string of characters developers add to their application code to license their use of applications built with ArcGIS Maps SDKs for Native Apps and to unlock certain capabilities on the deployment device. Learn more .
• Using a user authentication User authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0. Learn more workflow.

The option you choose will depend on the nature of your app and whether your app’s users will sign in to your app using an ArcGIS account.

License string

A license string A license string is a string of characters developers add to their application code to license their use of applications built with ArcGIS Maps SDKs for Native Apps and to unlock certain capabilities on the deployment device. Learn more is a text string provided by Esri that is used to enable a production license.

Your app must include code to apply the license string. See how to use a license string in your app for more details.

Your free Lite level license string is obtained from My Esri (sign in required). Basic, Standard, and Advanced license strings are purchased as ArcGIS Maps SDKs for Native Apps license deployment packs. See Get a license for more information.

A Lite license string includes unlimited production deployments.

For Basic, Standard, and Advanced license strings, the ArcGIS Maps SDKs for Native Apps license deployment pack defines how many production deployments are permitted (a deployment is counted per app, install, and user).

User authentication

User authentication User authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0. Learn more is an authentication method where a user signs in to your app with an ArcGIS account An ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription. Learn more in ArcGIS Online ArcGIS Online is a GIS mapping, analytics, data hosting, and content management software as a service (SaaS) product. It includes applications, tools, APIs, and location services for users and developers. It is subscription-based and requires an ArcGIS Online account. Learn more or ArcGIS Enterprise. ArcGIS Enterprise is a GIS mapping, analytics, data hosting, and content management product that can be hosted on-premise or in a cloud infrastructure. It includes software, applications, tools, APIs, and services for users and developers. Learn more The ArcGIS account of the user can be assigned a production license.

Your app should allow a user to sign in using their ArcGIS account, and must include code to read and apply the license associated with their authenticated account. See how to use user authentication in your app for more information.

The administrator of the ArcGIS organization to which your app user belongs must assign a suitable ArcGIS Maps SDKs for Native Apps license to your app user’s ArcGIS account. See Get a license for more information.

The production license obtained from user authentication travels with the user, not the app, allowing a user to license many apps.

How to use a license string in your app

Using a license string A license string is a string of characters developers add to their application code to license their use of applications built with ArcGIS Maps SDKs for Native Apps and to unlock certain capabilities on the deployment device. Learn more involves adding code during application development to set the license level so that the license string is built into the application.

1. Find a location in your code that runs before any SDK functionality is used.
2. Call the setLicense() method on the ArcGISRuntimeEnvironment singleton object to license the app with a license string and any extension licenses.

The following licensing code must run before any other ArcGIS Maps SDKs for Native Apps functionality is used in your app.

    // Create an error occurred signal connected to the ArcGISRuntimeEnvironment singleton.
    connect(ArcGISRuntimeEnvironment::instance(), &ArcGISRuntimeEnvironment::errorOccurred, [](Error error)
    {
        // TODO: handle any errors.
        qDebug() << "Error while licensing" << error.message() << error.additionalMessage();
    });

    // Add the following to the main.cpp before the application is loaded, using a license string available from Esri,
    // see: https://developers.arcgis.com/qt/license-and-deployment/get-a-license/
    // The above error occurred signal connect will be called if there is an error.
    const LicenseResult licenseResult = ArcGISRuntimeEnvironment::setLicense("your_license_string");

Your app is now licensed for production use.

How to use user authentication in your app

Use of user authentication User authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0. Learn more involves adding code to enable sign in with an ArcGIS account An ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription. Learn more . At runtime, a user must successfully sign in to return their license information, which is used by the app to set the license level. Follow these steps to license your app using the member’s account:

1. Find a location in your code that runs before any SDK functionality is used.
2. Allow the app user to authenticate with an ArcGIS organizational account. Upon loading the Portal obtain the LicenseInfo and use this to license the app. As part of the process, save the license information in preparation for the app being used in an offline environment for up to 30 days.

The following example shows how to get a license for an ArcGIS Online member.

    // Create an error occurred signal connected to the ArcGISRuntimeEnvironment singleton.
    connect(ArcGISRuntimeEnvironment::instance(), &ArcGISRuntimeEnvironment::errorOccurred, [](Error error)
    {
        // TODO: handle any errors.
        qDebug() << "Error while licensing" << error.message() << error.additionalMessage();
    });

    // Create a new portal using the boolean `true` which forces the login to occur.
    constexpr auto loginRequired = true;

    // Create a portal with a QUrl and login required boolean.
    Portal* portal = new Portal(QUrl("http://geoportal.mycompany.com/sharing/rest"), loginRequired, this);

    // Call the portal's fetch license info async method to obtain the license info.
    portal->fetchLicenseInfoAsync().then(this,[](const LicenseInfo& licenseInfo)
    {
        // The above error occurred signal connect will be called if there is an error.
        // Get the license result from the ArcGIS runtime environment.
        const LicenseResult licenseResult = ArcGISRuntimeEnvironment::setLicense(licenseInfo);
    });

Save the JSON containing the license information for use again later.

    // Get the json string from the license info.
    const QString json = licenseInfo.toJson();

    // Construct the file path to the license text file.
    QFile file(QDir::tempPath() + "/licenseFile.txt");

    // Test if the licence text file can open. If the file can't be opened,
    // display the result to the user.
    if (!file.open(QIODevice::WriteOnly | QIODevice::Truncate)) {
        qWarning() << "Cannot open license file:" << file.errorString();
        return;
    }

    // Write the json string. If the file can't be written, display the error.
    const QByteArray data = json.toUtf8();
    const qint64 written = file.write(data);
    if (written != data.size()) {
        qWarning() << "Incomplete write:" << written << "/" << data.size()
        << file.errorString();
        file.close();
        return;
    }

    // Close the file.
    file.close();

Your app is now licensed for production use.

If you saved the license information on local storage, your app can be started and licensed in an offline environment using the saved license information. Retrieve the license from storage and license your app.

    // Determine if the license text file exists. Display a message to
    // the user if there is a problem.
    if (!file.exists()) {
        qWarning() << "License file does not exist:" << file.fileName();
        return;
    }

    // Open the file. Display an error message if there is a problem.
    const bool opened = file.open(QIODevice::ReadOnly | QIODevice::Text);
    if (!opened) {
        qWarning() << "Failed to open license file:" << file.errorString();
        return;
    }

    // Read the file.
    const QByteArray jsonData = file.readAll();
    file.close();

    // Test if there is data in the file.
    if (jsonData.isEmpty()) {
        qWarning() << "License file is empty:" << file.fileName();
        return;
    }

    // Get the license info from the JSON.
    const LicenseInfo licenseInfo = LicenseInfo::fromJson(jsonData);

    // Get the license result from the ArcGIS runtime environment.
    const LicenseResult licenseResult = ArcGISRuntimeEnvironment::setLicense(licenseInfo);

    // Do more ...