Enable Intercom features for Capacitor apps
npm install @unsou/capacitor-intercom@unsou/capacitor-intercom
Capacitor plugin for enabling Intercom capabilities based on the Capacitor community plugin
Thanks for the all the authors with their work in @capacitor-community/intercom and in @foodello/intercom. We have noticed that the repository was left behind the newest updates and the original repository did not get updates quick enough once pull request were opened. So we decided to serve the newest Intercom capabilities under seperate org until the original repository catches the changes.
This plugin is built for the Capacitor v4 upwards.
Using npm:
``bash`
npm install @unsou/capacitor-intercom
Using yarn:
`bash`
yarn add @unsou/capacitor-intercom
Sync native files:
`bash`
npx cap sync
Import Intercom plugin into your project.
`js`
import { Capacitor } from '@capacitor/core';
import { Intercom } from '@unsou/capacitor-intercom';
import { PushNotifications } from '@capacitor/push-notifications';
Initialize Intercom plugin.
`js
/**
* Web requires loading and initializing the script of the SDK
* with the Intercom web config defined in IntercomWebConfig Interface.
*
* Only available in Web.
* @since 4.2.0
*/
if (!Capacitor.isNativePlatform()) {
await Intercom.load({ app_id: 'xxx' });
}
// Android and iOS does not require seperate initialization
`
* load(...)
* registerIdentifiedUser(...)
* loginIdentifiedUser(...)
* registerUnidentifiedUser()
* loginUnidentifiedUser()
* updateUser(...)
* logout()
* logEvent(...)
* displayMessenger()
* displayMessageComposer(...)
* displayHelpCenter()
* hideMessenger()
* displayLauncher()
* hideLauncher()
* displayInAppMessages()
* hideInAppMessages()
* displayCarousel(...)
* setUserHash(...)
* setBottomPadding(...)
* sendPushTokenToIntercom(...)
* receivePush(...)
* displayArticle(...)
* presentContent(...)
* present(...)
* setupUnreadConversationListener()
* removeUnreadConversationListener()
* getUnreadConversationCount()
* addListener('updateUnreadCount', ...)
* Interfaces
* Type Aliases
* Enums
IntercomPlugin Interface
`typescript`
load(config: IntercomWebConfig) => Promise
Load Intercom and set configs on Web environment.
Only available for Web
| Param | Type |
| ------------ | --------------------------------------------------------------- |
| config | IntercomWebConfig |
Since: 4.2.0
--------------------
`typescript`
registerIdentifiedUser(options: { userId?: string; email?: string; }) => Promise
| Param | Type |
| ------------- | ------------------------------------------------- |
| options | { userId?: string; email?: string; } |
Since: 1.0.0
--------------------
`typescript`
loginIdentifiedUser(options: { userId?: string; email?: string; }) => Promise
Login an identified user with Intercom.
| Param | Type |
| ------------- | ------------------------------------------------- |
| options | { userId?: string; email?: string; } |
Since: 4.1.0
--------------------
`typescript`
registerUnidentifiedUser() => Promise
Since: 1.0.0
--------------------
`typescript`
loginUnidentifiedUser() => Promise
Login an unidentified user with Intercom.
Since: 4.1.0
--------------------
`typescript`
updateUser(options: IntercomUserUpdateOptions) => Promise
Updates a user's attributes in Intercom.
| Param | Type |
| ------------- | ------------------------------------------------------------------------------- |
| options | IntercomUserUpdateOptions |
Since: 1.0.0
--------------------
`typescript`
logout() => Promise
Logs the user out of Intercom.
Since: 1.0.0
--------------------
`typescript`
logEvent(options: { name: string; data?: any; }) => Promise
Logs an event with optional metadata in Intercom.
| Param | Type |
| ------------- | ------------------------------------------ |
| options | { name: string; data?: any; } |
Since: 1.0.0
--------------------
`typescript`
displayMessenger() => Promise
Since: 1.0.0
--------------------
`typescript`
displayMessageComposer(options: { message: string; }) => Promise
Displays the Intercom Message Composer with an initial message.
| Param | Type |
| ------------- | --------------------------------- |
| options | { message: string; } |
Since: 1.0.0
--------------------
`typescript`
displayHelpCenter() => Promise
Since: 1.0.0
--------------------
`typescript`
hideMessenger() => Promise
Hides the Intercom Messenger.
Since: 1.0.0
--------------------
`typescript`
displayLauncher() => Promise
Displays the default Intercom Launcher.
Since: 1.0.0
--------------------
`typescript`
hideLauncher() => Promise
Hides the Intercom Launcher.
Since: 1.0.0
--------------------
`typescript`
displayInAppMessages() => Promise
Displays Intercom In-App Messages.
Since: 1.0.0
--------------------
`typescript`
hideInAppMessages() => Promise
Hides Intercom In-App Messages.
Since: 1.0.0
--------------------
`typescript`
displayCarousel(options: { carouselId: string; }) => Promise
| Param | Type |
| ------------- | ------------------------------------ |
| options | { carouselId: string; } |
Since: 1.0.0
--------------------
`typescript`
setUserHash(options: { hmac: string; }) => Promise
Sets the HMAC user hash for Intercom Identity Verification.
| Param | Type |
| ------------- | ------------------------------ |
| options | { hmac: string; } |
Since: 1.0.0
--------------------
`typescript`
setBottomPadding(options: { value: string; }) => Promise
Sets the bottom padding for the Intercom Messenger.
| Param | Type |
| ------------- | ------------------------------- |
| options | { value: string; } |
Since: 1.0.0
--------------------
`typescript`
sendPushTokenToIntercom(options: { value: string; }) => Promise
Sends a push token to Intercom.
| Param | Type |
| ------------- | ------------------------------- |
| options | { value: string; } |
Since: 1.0.0
--------------------
`typescript`
receivePush(notification: IntercomPushNotificationData) => Promise
Processes a received Intercom push notification.
| Param | Type |
| ------------------ | ------------------------------------------------------------------------------------- |
| notification | IntercomPushNotificationData |
Since: 1.0.0
--------------------
`typescript`
displayArticle(options: { articleId: string; }) => Promise
| Param | Type |
| ------------- | ----------------------------------- |
| options | { articleId: string; } |
Since: 1.0.0
--------------------
`typescript`
presentContent(options: { contentType: IntercomContent; contentId: string; }) => Promise
Presents an Intercom content item by its type and ID.
| Param | Type |
| ------------- | ------------------------------------------------------------------------------------------------ |
| options | { contentType: IntercomContent; contentId: string; } |
Since: 4.1.0
--------------------
`typescript`
present(options: { space: IntercomSpace; }) => Promise
Presents the Intercom's space.
| Param | Type |
| ------------- | ------------------------------- |
| options | { space: string; } |
Since: 4.1.0
--------------------
`typescript`
setupUnreadConversationListener() => Promise
Setup listener for unread conversation count updates.
Since: 4.1.0
--------------------
`typescript`
removeUnreadConversationListener() => Promise
Remove listener for unread conversation count updates.
Since: 4.1.0
--------------------
`typescript`
getUnreadConversationCount() => Promise<{ unreadCount: number; }>
Get current unread conversation count.
Returns: Promise<{ unreadCount: number; }>
Since: 4.1.0
--------------------
`typescript`
addListener(eventName: 'updateUnreadCount', listenerFunc: (data: { unreadCount: number; }) => void) => Promise
Listen for when the unread conversation count is changed.
| Param | Type |
| ------------------ | -------------------------------------------------------- |
| eventName | 'updateUnreadCount' |
| listenerFunc | (data: { unreadCount: number; }) => void |
Returns: Promise<PluginListenerHandle>
Since: 4.1.0
--------------------
#### IntercomWebConfig
IntercomWebConfig Interface
Represent configs that are available on Intercom Web SDK.
| Prop | Type | Description | Default | Since |
| ------------------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----- |
| app_id | string | Configure Intercom Web APP ID. The APP ID of your Intercom app which will indicate where to store any data. Only available for Web | | 4.2.0 |
| api_base | IntercomRegionalApiBase | Configure Intercom's regional API baseurl. For customers who are using Regional Data Hosting for Intercom, there is an additional parameter to set, to ensure your Messenger is pointing to your Regional workspace. Only available for Web | | 4.2.0 |
| custom_launcher_selector | string | Configure Intercom custom launcher selector. The CSS selector of an element to trigger Intercom("show") in order to activate the messenger. To target an element by ID: "#id_of_element". To target elements by class ".classname_of_elements" Only available for Web | | 4.2.0 |
| alignment | IntercomAlignment | Configure Intercom default launcher alignment. Dictate the alignment of the default launcher icon to be on the left/right. Possible values: "left" or "right" (any other value is treated as right). Only available for Web | "right" | 4.2.0 |
| vertical_padding | number | Configure Intercom default launcher icon's vertical padding. Move the default launcher icon vertically. Padding from bottom of screen. Minimum value: 20. Does not work on mobile. Only available for Web | | 4.2.0 |
| horizontal_padding | number | Configure Intercom default launcher icon's horizontal padding. Move the default launcher icon horizontally. Padding from right side of screen Minimum value: 20. Does not work on mobile. Only available for Web | | 4.2.0 |
| hide_default_launcher | boolean | Configure Intercom default launcher icon's visibility. Hide the default launcher icon. Setting to false will forcefully show the launcher icon. Only available for Web | | 4.2.0 |
| session_duration | number | Configure Intercom session duration. Time in milliseconds for the Intercom session to be considered active. A value of 5 60 1000 would set the expiry time to be 5 minutes Only available for Web | | 4.2.0 |
| action_color | string | Configure action color for Intercom. Used in button links and more to highlight and emphasise. The color string can be any valid CSS Color Name HEX or RGB Only available for Web | | 4.2.0 |
| background_color | string | Configure background color for Intercom. Used behind your team profile and other attributes. The color string can be any valid CSS Color Name HEX or RGB Only available for Web | | 4.2.0 |
#### IntercomUserUpdateOptions
IntercomUserUpdateOptions Interface
Represents the options for updating a user's attributes in Intercom.
Only available for iOS and Android.
| Prop | Type |
| ---------------------- | ------------------------------------------------------------ |
| userId | string |
| email | string |
| name | string |
| phone | string |
| languageOverride | string |
| customAttributes | Record<string, any> |
| company | CompanyOption |
| companies | CompanyOption[] |
#### CompanyOption
CompanyOption Interface.
Represents Intercom option to include company details.
| Prop | Type | Description |
| ---------------------- | ------------------------------------------------------------ | ----------------------------- |
| name | string | Required for Web |
| companyId | string | Required for Native platforms |
| createdAt | number | Unix timestamp |
| monthlySpend | number | |
| plan | string | |
| customAttributes | Record<string, any> | |
#### IntercomPushNotificationData
IntercomPushNotificationData Interface
Represents the structure of a received Intercom push notification.
Only available for iOS and Android.
| Prop | Type |
| ------------------------------- | ------------------- |
| conversation_id | string |
| message | string |
| body | string |
| author_name | string |
| image_url | string |
| app_name | string |
| receiver | string |
| conversation_part_type | string |
| intercom_push_type | string |
| uri | string |
| push_only_conversation_id | string |
| instance_id | string |
| title | string |
| priority | number |
#### PluginListenerHandle
| Prop | Type |
| ------------ | ----------------------------------------- |
| remove | () => Promise<void> |
#### Record
Construct a type with a set of properties K of type T
{
[P in K]: T;
}
#### IntercomSpace
typeof IntercomSpaces[keyof typeof IntercomSpaces]
#### IntercomRegionalApiBase
| Members | Value |
| -------- | --------------------------------------------- |
| Us | 'https://api-iam.intercom.io' |
| Eu | 'https://api-iam.eu.intercom.io' |
| Au | 'https://api-iam.au.intercom.io' |
#### IntercomAlignment
| Members | Value |
| ----------- | -------------------- |
| Left | 'left' |
| Right | 'right' |
#### IntercomContent
| Members | Value | Description | Since |
| --------------- | ------------------------ | ---------------------------------- | ----- |
| Article | 'article' | | |
| Survey | 'survey' | | |
| Carousel | 'carousel' | Only available for iOS and Android | 4.1.0 |
| Checklist | 'checklist' | Only available for Web | 4.2.0 |
| News | 'news' | Only available for Web | 4.2.0 |
| Tour | 'tour' | Only available for Web | 4.2.0 |
- ionic start my-cap-app --capacitorcd my-cap-app
- npm install β-save @foodello/intercom
- mkdir www && touch www/index.html
- npx cap add ios
-
- add intercom keys to capacitor's configuration file
``
{
β¦
"plugins": {
"Intercom": {
"iosApiKey": "ios_sdk-xxx",
"iosAppId": "yyy"
}
}
β¦
}
- npx cap open ios
- sign your app at xcode (general tab)
> Tip: every time you change a native code you may need to clean up the cache (Product > Clean build folder) and then run the app again.
- ionic start my-cap-app --capacitorcd my-cap-app
- npm install β-save @foodello/intercom
- mkdir www && touch www/index.html
- npx cap add android
-
- add intercom keys to capacitor's configuration file
``
{
β¦
"plugins": {
"Intercom": {
"androidApiKey": "android_sdk-xxx",
"androidAppId": "yyy"
}
}
β¦
}
- npx cap open android
Now you should be set to go. Try to run your client using ionic cap run android --livereload.
> Tip: every time you change a native code you may need to clean up the cache (Build > Clean Project | Build > Rebuild Project) and then run the app again.
MIT
This repository is based on the wonderful work of the official @capacitor-community/intercom` -plugin. Here we want to acknowledge the mastermind and sponsors behind that work.
Intenseloop |
| Maintainer | GitHub | Social |
| ------------ | --------------------------------------- | ----------------------------------------- |
| Stewan Silva | stewones | @stewones |
If you have any ideas what we should include, please open a new issue for it.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!