@unsou/capacitor-intercom

Capacitor Intercom plugin

@unsou/capacitor-intercom

Capacitor plugin for enabling Intercom capabilities based on the Capacitor community plugin

Notice 🚀

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.

Installation

Using npm:

``bash
npm install @unsou/capacitor-intercom
`

Using yarn:

`bash
yarn add @unsou/capacitor-intercom
`

Sync native files:

`bash
npx cap sync
`

Usage

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
`

API

* 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

$3

`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

--------------------

$3

`typescript
registerIdentifiedUser(options: { userId?: string; email?: string; }) => Promise
`

| Param | Type |
| ------------- | ------------------------------------------------- |
| options | { userId?: string; email?: string; } |

Since: 1.0.0

--------------------

$3

`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

--------------------

$3

`typescript
registerUnidentifiedUser() => Promise
`

Since: 1.0.0

--------------------

$3

`typescript
loginUnidentifiedUser() => Promise
`

Login an unidentified user with Intercom.

Since: 4.1.0

--------------------

$3

`typescript
updateUser(options: IntercomUserUpdateOptions) => Promise
`

Updates a user's attributes in Intercom.

| Param | Type |
| ------------- | ------------------------------------------------------------------------------- |
| options | IntercomUserUpdateOptions |

Since: 1.0.0

--------------------

$3

`typescript
logout() => Promise
`

Logs the user out of Intercom.

Since: 1.0.0

--------------------

$3

`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

--------------------

$3

`typescript
displayMessenger() => Promise
`

Since: 1.0.0

--------------------

$3

`typescript
displayMessageComposer(options: { message: string; }) => Promise
`

Displays the Intercom Message Composer with an initial message.

| Param | Type |
| ------------- | --------------------------------- |
| options | { message: string; } |

Since: 1.0.0

--------------------

$3

`typescript
displayHelpCenter() => Promise
`

Since: 1.0.0

--------------------

$3

`typescript
hideMessenger() => Promise
`

Hides the Intercom Messenger.

Since: 1.0.0

--------------------

$3

`typescript
displayLauncher() => Promise
`

Displays the default Intercom Launcher.

Since: 1.0.0

--------------------

$3

`typescript
hideLauncher() => Promise
`

Hides the Intercom Launcher.

Since: 1.0.0

--------------------

$3

`typescript
displayInAppMessages() => Promise
`

Displays Intercom In-App Messages.

Since: 1.0.0

--------------------

$3

`typescript
hideInAppMessages() => Promise
`

Hides Intercom In-App Messages.

Since: 1.0.0

--------------------

$3

`typescript
displayCarousel(options: { carouselId: string; }) => Promise
`

| Param | Type |
| ------------- | ------------------------------------ |
| options | { carouselId: string; } |

Since: 1.0.0

--------------------

$3

`typescript
setUserHash(options: { hmac: string; }) => Promise
`

Sets the HMAC user hash for Intercom Identity Verification.

| Param | Type |
| ------------- | ------------------------------ |
| options | { hmac: string; } |

Since: 1.0.0

--------------------

$3

`typescript
setBottomPadding(options: { value: string; }) => Promise
`

Sets the bottom padding for the Intercom Messenger.

| Param | Type |
| ------------- | ------------------------------- |
| options | { value: string; } |

Since: 1.0.0

--------------------

$3

`typescript
sendPushTokenToIntercom(options: { value: string; }) => Promise
`

Sends a push token to Intercom.

| Param | Type |
| ------------- | ------------------------------- |
| options | { value: string; } |

Since: 1.0.0

--------------------

$3

`typescript
receivePush(notification: IntercomPushNotificationData) => Promise
`

Processes a received Intercom push notification.

| Param | Type |
| ------------------ | ------------------------------------------------------------------------------------- |
| notification | IntercomPushNotificationData |

Since: 1.0.0

--------------------

$3

`typescript
displayArticle(options: { articleId: string; }) => Promise
`

| Param | Type |
| ------------- | ----------------------------------- |
| options | { articleId: string; } |

Since: 1.0.0

--------------------

$3

`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

--------------------

$3

`typescript
present(options: { space: IntercomSpace; }) => Promise
`

Presents the Intercom's space.

| Param | Type |
| ------------- | ------------------------------- |
| options | { space: string; } |

Since: 4.1.0

--------------------

$3

`typescript
setupUnreadConversationListener() => Promise
`

Setup listener for unread conversation count updates.

Since: 4.1.0

--------------------

$3

`typescript
removeUnreadConversationListener() => Promise
`

Remove listener for unread conversation count updates.

Since: 4.1.0

--------------------

$3

`typescript
getUnreadConversationCount() => Promise<{ unreadCount: number; }>
`

Get current unread conversation count.

Returns: Promise<{ unreadCount: number; }>

Since: 4.1.0

--------------------

$3

`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

--------------------

$3


#### 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> |

$3


#### Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }


#### IntercomSpace

typeof IntercomSpaces[keyof typeof IntercomSpaces]

$3


#### 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 |

Configurations

$3

- ionic start my-cap-app --capacitor
- cd 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.

$3

- ionic start my-cap-app --capacitor
- cd 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.

License

MIT

Original repository's maintainers and sponsors

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.

$3

Intenseloop

$3

| Maintainer | GitHub | Social |
| ------------ | --------------------------------------- | ----------------------------------------- |
| Stewan Silva | stewones | @stewones |

Future plans

If you have any ideas what we should include, please open a new issue for it.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Stew 💻 📖	David Seek 💻	Roman Nikitin 💻	Anne Tomassoni 💻 👀	Maciej Modzelewski 💻	Oleg Yuzvik 🚧	Gustavo Corrêa Alves 📖
Jealvia 🚧	Adam Duren 💻 🚧	Rami Khafagi 💻	Masahiko Sakakibara 🚧	Dejardin Camille 💻	Mohamed Abdelgwad 🚧	Nathan 🚧

This project follows the all-contributors specification. Contributions of any kind welcome!