Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[MOB-6374]: import docs discrepancy #211

Merged
merged 3 commits into from
Jun 21, 2023
Merged

[MOB-6374]: import docs discrepancy #211

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3ea4cb6
update readme with correct imports
mprew97 Jun 20, 2023
a8ed726
update readme with getInAppMessages
mprew97 Jun 20, 2023
b1df180
Update README.md
mprew97 Jun 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 35 additions & 42 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ Example:
Calling `getInAppMessages` with `options` not set returns a JSON response from Iterable. This response includes an `inAppMessages` field, and each item in the list has a `content.html` field that's an `iframe` with an embedded in-app message. The `iframe`'s `sandbox` attribute is set, isolating its render and preventing any malicious JavaScript execution.

```ts
import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
import { getInAppMessages } from '@iterable/web-sdk';

getInAppMessages({ count: 20, packageName: 'mySite1' })
.then((resp) => {
Expand All @@ -127,7 +127,7 @@ This code places an in-app on the page, but it won't be visible. To render it, y
Or, to show messages automatically:

```ts
import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
import { getInAppMessages } from '@iterable/web-sdk';

const { request, pauseMessageStream, resumeMessageStream } = getInAppMessages(
{
Expand Down Expand Up @@ -156,7 +156,7 @@ import {
getInAppMessages,
sortInAppMessages,
filterHiddenInAppMessages
} from '@iterable/web-sdk/dist/inapp';
} from '@iterable/web-sdk';

const {
request,
Expand Down Expand Up @@ -216,7 +216,7 @@ initialize: (authToken: string, generateJWT: ({ email?: string, userID?: string
Example:

```ts
import { initialize } from '@iterable/web-sdk/dist/authorization';
import { initialize } from '@iterable/web-sdk';

const { clearRefresh, setEmail, setUserID, logout } = initialize(
'my-API-key',
Expand All @@ -242,7 +242,7 @@ refreshJwtToken: (authTypes: string) => Promise<string>
Example:

```ts
import { initialize } from '@iterable/web-sdk/dist/authorization';
import { initialize } from '@iterable/web-sdk';

refreshJwtToken("user@example.com").then().catch();
```
Expand All @@ -259,7 +259,7 @@ track: (payload: InAppTrackRequestParams) => Promise<TrackData>
Example:

```ts
import { track } from '@iterable/web-sdk/dist/events';
import { track } from '@iterable/web-sdk';

track({ eventName: 'my-event' }).then().catch();
```
Expand All @@ -275,7 +275,7 @@ trackInAppClick: (payload: InAppEventRequestParams) => Promise<TrackClickData>
Example:

```ts
import { trackInAppClick } from '@iterable/web-sdk/dist/events';
import { trackInAppClick } from '@iterable/web-sdk';

trackInAppClick({
messageId: '123',
Expand All @@ -296,7 +296,7 @@ trackInAppClose: (payload: InAppEventRequestParams) => Promise<TrackCloseData>
Example:

```ts
import { trackInAppClose } from '@iterable/web-sdk/dist/events';
import { trackInAppClose } from '@iterable/web-sdk';

trackInAppClose({
messageId: '123',
Expand All @@ -317,7 +317,7 @@ trackInAppConsume: (payload: InAppEventRequestParams) => Promise<TrackConsumeDat
Example:

```ts
import { trackInAppConsume } from '@iterable/web-sdk/dist/events';
import { trackInAppConsume } from '@iterable/web-sdk';

trackInAppConsume({
messageId: '123',
Expand All @@ -338,7 +338,7 @@ trackInAppDelivery: (payload: InAppEventRequestParams) => Promise<TrackDeliveryD
Example:

```ts
import { trackInAppDelivery } from '@iterable/web-sdk/dist/events';
import { trackInAppDelivery } from '@iterable/web-sdk';

trackInAppDelivery({
messageId: '123',
Expand All @@ -359,7 +359,7 @@ trackInAppOpen: (payload: InAppEventRequestParams) => Promise<TrackOpenData>
Example:

```ts
import { trackInAppOpen } from '@iterable/web-sdk/dist/events';
import { trackInAppOpen } from '@iterable/web-sdk';

trackInAppOpen({
messageId: '123',
Expand All @@ -380,7 +380,7 @@ trackPurchase: (payload: TrackPurchaseRequestParams) => Promise<TrackPurchaseDat
Example:

```ts
import { trackPurchase } from '@iterable/web-sdk/dist/commerce';
import { trackPurchase } from '@iterable/web-sdk';

trackPurchase({
items: [{ id: '123', name: 'keyboard', price: 100, quantity: 2 }],
Expand All @@ -401,7 +401,7 @@ updateCart: (payload: UpdateCartRequestParams) => Promise<UpdateCartData>
Example:

```ts
import { updateCart } from '@iterable/web-sdk/dist/commerce';
import { updateCart } from '@iterable/web-sdk';

updateCart({
items: [{ id: '123', price: 100, name: 'keyboard', quantity: 1 }]
Expand All @@ -421,7 +421,7 @@ updateSubscriptions: (payload?: UpdateSubscriptionParams) => Promise<UpdateSubsD
Example:

```ts
import { updateSubscriptions } from '@iterable/web-sdk/dist/users';
import { updateSubscriptions } from '@iterable/web-sdk';

updateSubscriptions({ emailListIds: [1, 2, 3] })
.then()
Expand All @@ -439,7 +439,7 @@ updateUser: (payload?: UpdateUserParams) => Promise<UpdateUserData>
Example:

```ts
import { updateUser } from '@iterable/web-sdk/dist/users';
import { updateUser } from '@iterable/web-sdk';

updateUser({ dataFields: {} }).then().catch();
```
Expand All @@ -455,7 +455,7 @@ updateUserEmail: (newEmail: string) => Promise<UpdateEmailData>
Example:

```ts
import { updateUserEmail } from '@iterable/web-sdk/dist/users';
import { updateUserEmail } from '@iterable/web-sdk';

updateUserEmail('user@example.com').then().catch();
```
Expand All @@ -472,7 +472,7 @@ First, you'll deal with the JWT Secret. Typically, you need some backend service
Once you have a JWT or a service that can generate a JWT automatically, you're ready to start making requests in the SDK. The syntax for that looks like this:

```ts
import { initialize } from '@iterable/web-sdk/dist/authorization';
import { initialize } from '@iterable/web-sdk';

(() => {
initialize('YOUR_API_KEY_HERE', ({ email, userID }) =>
Expand All @@ -488,7 +488,7 @@ Now that we've set our authorization logic within our app, it's time to set the
The syntax for identifying a user by user ID looks like this:

```ts
import { initialize } from '@iterable/web-sdk/dist/authorization';
import { initialize } from '@iterable/web-sdk';

(() => {
const { setUserID, logout } = initialize(
Expand All @@ -514,7 +514,7 @@ import { initialize } from '@iterable/web-sdk/dist/authorization';
Doing this with an email is similar:

```ts
import { initialize } from '@iterable/web-sdk/dist/authorization';
import { initialize } from '@iterable/web-sdk';

(() => {
const { setEmail, logout } = initialize(
Expand Down Expand Up @@ -543,8 +543,7 @@ import { initialize } from '@iterable/web-sdk/dist/authorization';
Now let's put it altogether with an Iterable API method:

```ts
import { initialize } from '@iterable/web-sdk/dist/authorization';
import { track } from '@iterable/web-sdk/dist/events';
import { initialize, track } from '@iterable/web-sdk';

(() => {
const { setUserID, logout } = initialize(
Expand Down Expand Up @@ -576,16 +575,16 @@ This SDK relies on a library called [Axios](https://github.com/axios/axios). For

## Ok cool. What if I want to handle this intercepting logic myself instead?

You can do that! This SDK exposes the base Axios instance so you can do whatever you like with it and build upon that. You can import the Axios instance like so and anything in the Axios documentation is fair game to use:
You can do that! This SDK exposes the base Axios request instance so you can do whatever you like with it and build upon that. You can import the Axios request like so and anything in the Axios documentation is fair game to use:

```ts
import { baseAxiosInstance } from '@iterable/web-sdk/dist/request';
import { baseAxiosRequest } from '@iterable/web-sdk';
```

For example, if you want to set an `email` query param on every outgoing request, you would just implement the way Axios advises like so:

```ts
import { baseAxiosRequest } from '@iterable/web-sdk/dist/request';
import { baseAxiosRequest } from '@iterable/web-sdk';

(() => {
baseAxiosRequest.interceptors.request.use((config) => {
Expand All @@ -604,13 +603,12 @@ import { baseAxiosRequest } from '@iterable/web-sdk/dist/request';

## I want to automatically show my in-app messages with a delay between each

This SDK allows that. Simply call the `getMessages` method but pass `{ display: 'immediate' }` as the second parameter. This will expose some methods used to make the request to show the messages and pause and resume the queue.
This SDK allows that. Simply call the `getInAppMessages` method but pass `{ display: 'immediate' }` as the second parameter. This will expose some methods used to make the request to show the messages and pause and resume the queue.

Normally to request a list of in-app messages, you'd make a request like this:

```ts
import { initialize } from '@iterable/web-sdk/dist/authorization';
import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
import { initialize, getInAppMessages } from '@iterable/web-sdk';

(() => {
const { setUserID } = initialize('YOUR_API_KEY_HERE', ({ email, userID }) =>
Expand All @@ -635,8 +633,7 @@ import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
In order to take advantage of the SDK showing them automatically, you would implement the same method in this way:

```ts
import { initialize } from '@iterable/web-sdk/dist/authorization';
import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
import { initialize, getInAppMessages } from '@iterable/web-sdk';

(() => {
const { setUserID } = initialize('YOUR_API_KEY_HERE', ({ email, userID }) =>
Expand Down Expand Up @@ -665,8 +662,7 @@ import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
Optionally, you can pass arguments to fine-tune how you want the messages to appear. See the [usage section](#getInAppMessages) to see all available options and what they do.

```ts
import { initialize } from '@iterable/web-sdk/dist/authorization';
import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
import { initialize, getInAppMessages } from '@iterable/web-sdk';

(() => {
const { setUserID } = initialize('YOUR_API_KEY_HERE', ({ email, userID }) =>
Expand Down Expand Up @@ -704,8 +700,7 @@ import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
You can also pause and resume the messages stream if you like

```ts
import { initialize } from '@iterable/web-sdk/dist/authorization';
import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
import { initialize, getInAppMessages } from '@iterable/web-sdk';

(() => {
const { setUserID } = initialize('YOUR_API_KEY_HERE', ({ email, userID }) =>
Expand Down Expand Up @@ -744,12 +739,12 @@ import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
Finally, you can also choose to do your own manipulation to the messages before choosing to display them:

```ts
import { initialize } from '@iterable/web-sdk/dist/authorization';
import {
initialize,
getInAppMessages,
sortInAppMessages,
filterHiddenInAppMessages
} from '@iterable/web-sdk/dist/inapp';
} from '@iterable/web-sdk';

(() => {
const { setUserID } = initialize('YOUR_API_KEY_HERE', ({ email, userID }) =>
Expand Down Expand Up @@ -826,7 +821,7 @@ JWT expiration is handled for you automatically by the SDK. There are 3 points w
As previously explained, when initializing the SDK you need to pass a function that returns a Promise with the JWT, which looks something like this:

```ts
import { initialize } from '@iterable/web-sdk/dist/authorization';
import { initialize } from '@iterable/web-sdk';

initialize('API_KEY_HERE', ({ email, userID }) =>
yourAsyncJWTGenerationMethod({ email, userID }).then(
Expand All @@ -850,9 +845,7 @@ import { getInAppMessages, initialize, updateUser } from '@iterable/web-sdk';
```

```ts
import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
import { initialize } from '@iterable/web-sdk/dist/authorization';
import { updateUser } from '@iterable/web-sdk/dist/users';
import { initialize, getInAppMessages, updateUser } from '@iterable/web-sdk';
```

For those using Webpack/Rollup/Some Other Build Tool, it is recommended to import methods with the later approach for smaller final bundles. Importing with the second method ensures your bundle will only include the code you're using and not the code you're not.
Expand All @@ -863,12 +856,12 @@ Since the Web SDK renders in-app messages in an iframe element on your website i

But there are few features which the SDK adds so that you can customize how you'd like links to behave:

First, the [`handleLinks` option](#getInAppMessages) within the `getMessages` call will allow you to either open all links in a new tab, the same tab, or ensure that external links open in a new tab, while internal ones keep the experience within the same tab. So for example, this code:
First, the `handleLinks` option provided by [`getInAppMessages`](#getInAppMessages) allows you to specify how the SDK opens links: in the current tab, in a new tab, or a combination (external links in a new tab, internal links in the current tab). For example, this code:

```ts
import { getMessages } from '@iterable/web-sdk/dist/inapp';
import { getInAppMessages } from '@iterable/web-sdk';

getMessages({
getInAppMessages({
count: 5,
packageName: 'my-website',
handleLinks: 'external-new-tab'
Expand Down