Important: Please read the Qt Code of Conduct -

How to automatically launch iOS app with parameters

  • Qt 5.12

    I'd like to launch our iOS app with some optional parameters unique to the user (an operating mode, a server URL and access key). If the app is launched without these, the user is prompted to enter these on startup. On the desktop, these parameters can be specified as arguments on the command line.

    It looks like the way to do this on iOS is through a URL with a custom scheme. I've added CFBundleURLTypes to the Info.plist and I can now launch my app from a browser with a custom URL like:


    So far so good.

    The bit I'm struggling with is how to read the URL parameters and pass them into the application. I can see there is the setUrlHandler() method on the QDesktopServices class documented at and referenced at but if I set the URL handler once the app is launched it will be too late won't it?

    Elsewhere I see people extending QIOSApplicationDelegate but I don't understand how this would glue together with my application.

    Has anyone done this before? Am I going about it the right way?

  • I got it working for a URL like camcops:// and the same on Android but with http scheme. That seems to be the preferred approach on each platform. Unfortunately some email clients such as GMail do not display URLs with unknown schemes as hyperlinks, even if they are within <a> elements in HTML.

    Full code is at under GPL V3

    Here are some highlights:



    In the main application:

       auto url_handler = UrlHandler::getInstance();
       connect(url_handler, &UrlHandler::defaultSingleUserModeSet,
               this, &CamcopsApp::setDefaultSingleUserMode);
       connect(url_handler, &UrlHandler::defaultServerLocationSet,
               this, &CamcopsApp::setDefaultServerLocation);
       connect(url_handler, &UrlHandler::defaultAccessKeySet,
               this, &CamcopsApp::setDefaultAccessKey);


    UrlHandler* UrlHandler::m_instance = NULL;
        m_instance = this;
        QDesktopServices::setUrlHandler("camcops", this, "handleUrl");
    void UrlHandler::handleUrl(const QUrl url)
        auto query = QUrlQuery(url);
        auto default_single_user_mode = query.queryItemValue("default_single_user_mode");
        if (!default_single_user_mode.isEmpty()) {
            emit defaultSingleUserModeSet(default_single_user_mode);
        auto default_server_location = query.queryItemValue("default_server_location",
        if (!default_server_location.isEmpty()) {
            emit defaultServerLocationSet(default_server_location);
        auto default_access_key = query.queryItemValue("default_access_key");
        if (!default_access_key.isEmpty()) {
            emit defaultAccessKeySet(default_access_key);
    UrlHandler* UrlHandler::getInstance()
        if (!m_instance)
            m_instance = new UrlHandler;
        return m_instance;

    Android doesn't support the same approach so we have to write some Java:

    public class CamcopsActivity extends QtActivity
        // Defined in urlhandler.cpp
        public static native void handleAndroidUrl(String url);
        public void onCreate(Bundle savedInstanceState) {
            // Called when no instance of the app is running. Pass URL parameters
            // as arguments to the app's main()
            Intent intent = getIntent();
            if (intent != null && intent.getAction() == Intent.ACTION_VIEW) {
                Uri uri = intent.getData();
                if (uri != null) {
                    Log.i(TAG, intent.getDataString());
                    Map<String, String> parameters = getQueryParameters(uri);
                    StringBuilder sb = new StringBuilder();
                    String separator = "";
                    for (Map.Entry<String, String> entry : parameters.entrySet()) {
                        String name = entry.getKey();
                        String value = entry.getValue();
                        if (value != null) {
                            separator = "\t";
                    APPLICATION_PARAMETERS = sb.toString();
        public void onNewIntent(Intent intent) {
            /* Called when the app is already running. Send the URL parameters
             * as signals to the app.
        private void sendUrlToApp(Intent intent) {
            String url = intent.getDataString();
            if (url != null) {
        private Map<String, String> getQueryParameters(Uri uri) {
            List<String> names = Arrays.asList("default_single_user_mode",
            Map<String, String> parameters = new HashMap<String, String>();
            for (String name : names) {
                String value = uri.getQueryParameter(name);
                if (value != null) {
                    parameters.put(name, value);
            return parameters;


    #ifdef Q_OS_ANDROID
    // Called from android/src/org/camcops/camcops/
    #ifdef __cplusplus
    extern "C" {
          JNIEnv *env,
          jobject obj,
          jstring url)
        const char *url_str = env->GetStringUTFChars(url, NULL);
        env->ReleaseStringUTFChars(url, url_str);
    #ifdef __cplusplus

    and then in AndroidManifest.xml:

    <activity ... android:name="org.camcops.camcops.CamcopsActivity" ... launchMode="singleTask">
           <action android:name="android.intent.action.VIEW"/>
           <category android:name="android.intent.category.DEFAULT"/>
           <category android:name="android.intent.category.BROWSABLE"/>
           <data android:scheme="http" android:host="" android:path="/register/"/>

  • Lifetime Qt Champion


    Wouldn't it be simpler to store these in settings and load them from there ?

  • @SGaist Possibly. I wasn't aware of QSettings. Now I am. Thank you.

    This defaults are only needed the first time the app is used for registration. Any other user settings we store encrypted in a SQLite database.

  • Lifetime Qt Champion

    I may have misunderstood something. You users will receive these information in an email to get started ?

  • @SGaist Yes exactly. It's an app for completing medical tasks such as questionnaires. The patients are set up on a server and emailed a URL with a unique access key and a server address. The first time the app is used, it registers with the server and downloads the questionnaires. After that the URL is no longer needed.

Log in to reply