Get Started with Firebase Invites for C++

To write your cross-platform Firebase Invites client app with C++, use the Firebase Invites API. The C++ SDK works for both Android and iOS, with some additional setup required for each platform.

Before you begin

Android

  1. If you haven't yet connected your app to your Firebase project, do so from the Firebase console.
  2. If you haven't yet enabled Firebase Dynamic Links, do so from the Firebase console by opening the Dynamic Links section and accepting the terms of service if prompted. Because Firebase Invites is built on Firebase Dynamic Links, you must enable Firebase Dynamic Links to use Firebase Invites.
  3. Add Firebase to your Android project.
  4. Add the dependency for Firebase Invites to your app-level build.gradle file:
    dependencies {
         compile 'com.google.firebase:firebase-invites:11.4.2'
    }
  5. Link the libapp.a and libinvites.a static library, from the C++ SDK.

iOS

  1. If you haven't yet connected your app to your Firebase project, do so from the Firebase console.
  2. If you haven't yet enabled Firebase Dynamic Links, do so from the Firebase console by opening the Dynamic Links section and accepting the terms of service if prompted. Because Firebase Invites is built on Firebase Dynamic Links, you must enable Firebase Dynamic Links to use Firebase Invites.
  3. Add Firebase to your iOS project.
  4. The Firebase Invites C++ client library uses Google Sign-In on iOS. Users must be signed in to send invitations, and you must add custom URL schemes to your app to support this:
    1. To open your project configuration, double-click the project name in the left tree view. Select your app from the TARGETS section, then select the Info tab, and expand the URL Types section.
    2. Click the + button, and add a URL scheme for your reversed client ID. To find this value, open the GoogleService-Info.plist configuration file, and look for the REVERSED_CLIENT_ID key. Copy the value of that key, and paste it into the URL Schemes box on the configuration page. Leave the other fields blank.
    3. Click the + button, and add a second URL scheme. This one is the same as your app's bundle ID. For example, if your bundle ID is com.example.app, type that value into the URL Schemes box. You can find your app's bundle ID in the General tab of the project configuration (Identity > Bundle Identifier).
  5. Include the following Pod in your Podfile:
    pod 'Firebase/Invites'
  6. Run pod install
  7. Add firebase.framework and firebase_invites.framework, from the C++ SDK, to your Xcode project.

Sending invitations

Create and initialize App

Before you can send invitations, you'll need to create and initialize a firebase::App object.

Include the header file for firebase::App:

#include "firebase/app.h"

The next part varies depending on your platform:

Android

Create the firebase::App, passing the JNI environment and a jobject reference to the Java Activity as arguments:

app = ::firebase::App::Create(::firebase::AppOptions("APPLICATION NAME"), jni_env, activity);

iOS

Create the firebase::App:

app = ::firebase::App::Create(::firebase::AppOptions("APPLICATION NAME"));

Create and configure the Invite

Include the header file for sending Invites:

#include "firebase/invites.h"

Initialize the Invites library:

::firebase::invites::Initialize(app);

Create an new instance of firebase::invites::Invite, then configure it with your invitation settings:

firebase::invites::Invite invite;
invite.title_text = "Invite Friends";
invite.message_text = "Try my app today, and get 200 free coins!";
invite.call_to_action_text = "Download now!";

See here for the full list of invitation settings, including which ones are supported on each platform.

For more information on customizing invitations, see Firebase Invites: Best Practices.

Send the invitation

When you are ready to display the invitation, call SendInvite():

firebase::invites::SendInvite(invite);

This will display the Invites client UI, allowing the user to choose the recipients and modify the message if desired. This UI will stay on the screen until the user chooses to either send the invitation or cancel.

SendInvite() returns immediately and displays the UI asynchronously. It returns its results via firebase::Future, which you can query to find out whether the invitation was sent and determine when the UI is no longer on screen.

You can also obtain the most recent firebase::Future by calling SendInviteLastResult(). This returns the same result as the most recent call to SendInvite().

auto future_result = firebase::invites::SendInviteLastResult();
if (future_result.status() == future::kFutureStatusComplete) {
    if (future_result.error() == 0) {
        auto result = *future.result();
        if (result.invitation_ids.size() > 0) {
            // One or more invitations were sent. You can log the invitation IDs here for
            // analytics purposes, as they will be the same on the receiving side.
        }
        else {
            // Zero invitations were sent. This tells us that the user canceled sending
            // invitations.
        }
    } else {
        // error() is nonzero, which means an error occurred. You can check
        // future_result.error_message() for more information.
    }
} else {
    // The SendInvite() operation has not completed yet, which means the Invites
    // client UI is still on screen. Check the status() again soon.
}

You can also use OnCompletion() to set a callback to be notified when SendInvite() completes (which tells you the Invites UI is finished), instead of polling status(). See the firebase::Future documentation for more details.

Cross-platform invitations

If your project in the Firebase console contains exactly one application for each platform, Firebase Invites will automatically associate the applications with each other, so that (for example) iOS users clicking on an invitation sent by an Android user will be sent to the right place to install your app on their platform.

If you have more than one application on each platform, you can set ios_platform_client_id or android_platform_client_id, passing in the Firebase client ID of the alternate platform.

Receiving invitations

When a user receives an invitation, if the user has not yet installed the app, they can choose to install the app from their platform's app store.

Then, after the app is installed, or if the app was already installed, the app starts and receives the URL to its content, if you sent one. The app will also receive the invitation ID, which will match the invitation ID on the sending side.

Generally, your app should check for incoming invitations once, at startup.

Create and initialize App

Before you can check for received invitations, you'll need to create and initialize a firebase::App object.

Include the header file for firebase::App:

#include "firebase/app.h"

The next part varies depending on your platform:

Android

Create the firebase::App, passing the JNI environment and a jobject reference to the Java Activity as arguments:

app = ::firebase::App::Create(::firebase::AppOptions("APPLICATION NAME"), jni_env, activity);

iOS

Create the firebase::App:

app = ::firebase::App::Create(::firebase::AppOptions("APPLICATION NAME"));

Implement Listener and check for an incoming invitation

Include the header file for receiving Invites:

#include "firebase/invites.h"

Initialize the Invites library:

::firebase::invites::Initialize(app);

Create an object that implements firebase::invites::Listener, and supply it to the Invites library with SetListener().

To receive invitations, your Listener class must implement the OnInviteReceived virtual function. By overriding the method, you can receive an invitation ID if one was received.

void OnInviteReceived(const char* invitation_id, const char* deep_link,
                      bool is_strong_match) override {
  // Fetch succeeded, let's find out what we received.
  if (invitation_id != nullptr) {
    // The app received an invitation ID. This will match the invitation ID
    // that the sender got when they sent the invitation, so you can use this
    // to track when invitations are completed.
  }
  if (deep_link != nullptr) {
    // The app received a Dynamic Link. This may have come from an invitation
    // (if invite.invitation_id is set), or it might have been sent using
    // Firebase Dynamic Links.
    // In any event, the app can now act on this link as you see fit.
  }
}

Send feedback about...

Need help? Visit our support page.