准备工作
- 如果您尚未将自己的应用与 Firebase 项目相关联,请在 Firebase 控制台中进行关联。在关联您的应用时,请务必指定 SHA-1 签名密钥。
- 如果您尚未启用 Firebase 动态链接,请在 Firebase 控制台中打开“动态链接”(Dynamic Links) 部分,然后在看到提示时接受服务条款,以启用动态链接。由于 Firebase 邀请基于 Firebase 动态链接构建而成,因此您必须启用 Firebase 动态链接,方可使用 Firebase 邀请。
- 将 Firebase 添加到您的 Android 项目。
- 将 Firebase 邀请的以下依赖项添加到您的应用级
build.gradle
文件:implementation 'com.google.firebase:firebase-invites:17.0.0'
发送邀请
首先,构建一个 Intent
(使用 AppInviteInvitation.IntentBuilder
类):
Java
private void onInviteClicked() { Intent intent = new AppInviteInvitation.IntentBuilder(getString(R.string.invitation_title)) .setMessage(getString(R.string.invitation_message)) .setDeepLink(Uri.parse(getString(R.string.invitation_deep_link))) .setCustomImage(Uri.parse(getString(R.string.invitation_custom_image))) .setCallToActionText(getString(R.string.invitation_cta)) .build(); startActivityForResult(intent, REQUEST_INVITE); }
Kotlin
private fun onInviteClicked() { val intent = AppInviteInvitation.IntentBuilder(getString(R.string.invitation_title)) .setMessage(getString(R.string.invitation_message)) .setDeepLink(Uri.parse(getString(R.string.invitation_deep_link))) .setCustomImage(Uri.parse(getString(R.string.invitation_custom_image))) .setCallToActionText(getString(R.string.invitation_cta)) .build() startActivityForResult(intent, REQUEST_INVITE) }
自定义邀请
构建邀请 Intent
时,您必须指定邀请对话框的标题和要发送的邀请消息。您还可以自定义在邀请中发送的图片和深层链接网址(如上例所示),并且可以指定 HTML 以发送富媒体电子邮件邀请(推荐)。请参阅 Firebase 邀请:最佳做法。
方法 | 渠道 | 说明 |
---|---|---|
setMessage |
电子邮件和短信 | 设置通过邀请发送的默认消息。此消息可由发件人在邀请对话框中进行编辑。不能超过 100 个字符。 |
setDeepLink |
电子邮件和短信 | 设置通过邀请发送的指向应用的链接。指定此链接以便与收件人分享特定的内容,或者在用户通过邀请打开您的应用时为其提供定制体验。 |
setCustomImage |
电子邮件 | 设置要包含在电子邮件邀请中的自定义图片的网址。图片必须为正方形,且大小约为 600x600 像素。图片不能大于 4000x4000 像素。 |
setCallToActionText |
电子邮件 | 设置在电子邮件邀请中显示的按钮的号召性用语文本。不能超过 32 个字符。 |
setEmailHtmlContent |
电子邮件 | 推荐:设置电子邮件邀请的内容。设置此内容以发送 HTML 富媒体电子邮件邀请。您的 HTML 应包含占位字符串 %%APPINVITE_LINK_PLACEHOLDER%% ,其会被替换成可供收件人打开用于接受邀请的网址。当您指定自定义电子邮件消息时,setDescription 、setCustomImage 和 setCallToActionText 方法无效。 |
setEmailSubject |
电子邮件 | 如果使用了 setEmailHtmlContent ,则必须使用此方法。设置电子邮件邀请的主题行。 |
如果您的应用有 iOS 版本,并且想要发送可以在 Android 设备及 iOS 设备上打开的邀请,可在构建应用邀请 intent 时将您的 iOS 应用的 OAuth 2.0 客户端 ID 传递给 setOtherPlatformsTargetApplication
。您可以在从 Firebase 控制台下载的 GoogleService-Info.plist
文件中找到您的 iOS 应用的客户端 ID。例如:
Java
Intent intent = new AppInviteInvitation.IntentBuilder(getString(R.string.invitation_title)) // ... .setOtherPlatformsTargetApplication( AppInviteInvitation.IntentBuilder.PlatformMode.PROJECT_PLATFORM_IOS, IOS_APP_CLIENT_ID) // ... .build();
Kotlin
val intent = AppInviteInvitation.IntentBuilder(getString(R.string.invitation_title)) // ... .setOtherPlatformsTargetApplication( AppInviteInvitation.IntentBuilder.PlatformMode.PROJECT_PLATFORM_IOS, IOS_APP_CLIENT_ID) // ... .build()
启动 AppInviteInvitation
intent 会打开联系人选择器,用户可以从中选择要邀请的联系人。邀请通过电子邮件或短信发送。用户选择联系人并发送邀请后,您的应用会接收到对 onActivityResult
的回调:
Java
@Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); Log.d(TAG, "onActivityResult: requestCode=" + requestCode + ", resultCode=" + resultCode); if (requestCode == REQUEST_INVITE) { if (resultCode == RESULT_OK) { // Get the invitation IDs of all sent messages String[] ids = AppInviteInvitation.getInvitationIds(resultCode, data); for (String id : ids) { Log.d(TAG, "onActivityResult: sent invitation " + id); } } else { // Sending failed or it was canceled, show failure message to the user // ... } } }
Kotlin
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) Log.d(TAG, "onActivityResult: requestCode=$requestCode, resultCode=$resultCode") if (requestCode == REQUEST_INVITE) { if (resultCode == Activity.RESULT_OK) { // Get the invitation IDs of all sent messages val ids = AppInviteInvitation.getInvitationIds(resultCode, data!!) for (id in ids) { Log.d(TAG, "onActivityResult: sent invitation $id") } } else { // Sending failed or it was canceled, show failure message to the user // ... } } }
接收邀请
如果在收到邀请时尚未安装应用,那么用户可以选择从 Google Play 商店安装应用。在用户安装您的应用后(或如果用户已安装您的应用),应用会启动并接收指向其内容的网址(如果您已发送)。要获取指向应用内容的网址,请调用 getDynamicLink
方法:
Java
@Override protected void onCreate(Bundle savedInstanceState) { // ... // Check for App Invite invitations and launch deep-link activity if possible. // Requires that an Activity is registered in AndroidManifest.xml to handle // deep-link URLs. FirebaseDynamicLinks.getInstance().getDynamicLink(getIntent()) .addOnSuccessListener(this, new OnSuccessListener<PendingDynamicLinkData>() { @Override public void onSuccess(PendingDynamicLinkData data) { if (data == null) { Log.d(TAG, "getInvitation: no data"); return; } // Get the deep link Uri deepLink = data.getLink(); // Extract invite FirebaseAppInvite invite = FirebaseAppInvite.getInvitation(data); if (invite != null) { String invitationId = invite.getInvitationId(); } // Handle the deep link // ... } }) .addOnFailureListener(this, new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { Log.w(TAG, "getDynamicLink:onFailure", e); } }); }
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { // ... // Check for App Invite invitations and launch deep-link activity if possible. // Requires that an Activity is registered in AndroidManifest.xml to handle // deep-link URLs. FirebaseDynamicLinks.getInstance().getDynamicLink(intent) .addOnSuccessListener(this, OnSuccessListener { data -> if (data == null) { Log.d(TAG, "getInvitation: no data") return@OnSuccessListener } // Get the deep link val deepLink = data.link // Extract invite val invite = FirebaseAppInvite.getInvitation(data) val invitationId = invite.invitationId // Handle the deep link // ... }) .addOnFailureListener(this) { e -> Log.w(TAG, "getDynamicLink:onFailure", e) } }
您必须在动态链接可能启动的每个 Activity 中调用 getDynamicLink()
来获取该链接,即使您有可能使用 getIntent().getData()
从 intent 中获取该链接也是如此。调用 getDynamicLink()
可获取该链接和邀请 ID 并清除相关数据,因此您的应用只会对其处理一次。
通常应该在主要 Activity 以及由与链接匹配的 intent 过滤器启动的所有 Activity 中调用 getDynamicLink()
。