Before you begin
Android
- If you haven't yet connected your app to your Firebase project, do so from the Firebase console.
- 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.
- Add Firebase to your Android project.
- Add the dependency for Firebase Invites to your app-level
build.gradle
file:dependencies { compile 'com.google.firebase:firebase-invites:9.6.1' }
- Link the
libapp.a
andlibinvites.a
static library, from the C++ SDK.
iOS
- If you haven't yet connected your app to your Firebase project, do so from the Firebase console.
- 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.
- Add Firebase to your iOS project.
- 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:
- 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.
- 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 theREVERSED_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. - 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).
- Include the following Pod in your
Podfile
:pod 'Firebase/Invites'
- Run
pod install
- Add
firebase.framework
andfirebase_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 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:
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 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.