Get Started with Firebase Invites for C++

Before you begin

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:

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

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

Create and configure InvitesSender

Include the header file for sending Invites:

#include "firebase/invites/sender.h"

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

sender = new firebase::invites::InvitesSender(*app);
sender->SetTitleText("Invite Friends");
sender->SetMessageText("Try my app today, and get 200 free coins!");
sender->SetCallToActionText("Download now!");

See here for the full list of invitation settings (all beginning with Set), 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():

sender->SendInvite();

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 = sender->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.ErrorMessage() 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 call SetOtherPlatformClientID() from each platform, 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:

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

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

Create InvitesReceiver and check for an incoming invitation

Include the header file for receiving Invites:

#include "firebase/invites/receiver.h"

Create an new instance of firebase::invites::InvitesReceiver, and fetch any incoming invitation.

receiver = new firebase::invites::InvitesReceiver(*app);
receiver->Fetch();

Fetch() returns immediately and checks for the invitation asynchronously. It returns its results via firebase::Future, which you can query to find out whether an invitation (or Dynamic Link) was received.

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

auto future_result = receiver->FetchLastResult();
if (future_result.Status() == firebase::kFutureStatusComplete) {
    if (future_result.Error() == 0) {
        // Fetch succeeded, let's find out what we received.
        auto result = *future_result.Result();
        if (result.invitation_id != "") {
            // 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 (result.deep_link != "") {
            // The app received a Dynamic Link. This may have come from an invitation
            // (if result.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.
        }
        if (result.invitation_id == "" && result.deep_link == "") {
            // The app did not receive any invitation or Dynamic Link, so carry on as normal.
        }
    } else {
        // Error() is nonzero, which means an error occurred. You can check
        // future_result.ErrorMessage() for more information.
    }
} else {
    // The Fetch() operation has not completed yet, so the Invites library is
    // still checking for an incoming invitation. Check the Status() again soon.
}

You can also use OnCompletion() to set a callback to be notified when Fetch() completes, instead of polling Status(). See the firebase::Future documentation for more details.