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

Documentation - remove references to deprecated features #222

Open
wants to merge 4 commits into
base: release/0.10.0
Choose a base branch
from
Open

Documentation - remove references to deprecated features #222

Changes from 4 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fa3bae5
Merge branch 'master' into feature/deprecate-identity
sbellity Dec 9, 2019
a3b7366
Remove mentions to deprecated identity and ships injection features
sbellity Dec 9, 2019
f56b422
Merge branch 'release/0.10.0' into feature/deprecate-identity
sbellity Mar 10, 2020
2e779c0
DOCUMENTATION remove duplicated section
sbellity Mar 10, 2020
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
154 changes: 11 additions & 143 deletions DOCUMENTATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ It also lets you easily embed certain connectors in the page to inject functiona

It is the library you install when you paste a Platform snippet in your page's `HEAD` tag.

# Booting Hull
To generate the Hull.js snippet for your website, first head to the Guides section ["Getting Started with Hull.js"](https://www.hull.io/docs/guides/getting-started/getting-started-hull-js)

# Starting Hull

> Automatic initialization

Expand Down Expand Up @@ -55,39 +57,34 @@ autoStart | String | Default: `true`, Auto Start Hull on load (call `Hull.init()
embed | Boolean | Default:`true`. Skip embedding connectors in the page.
debug | Boolean | Default:`false`. Log messages. VERY useful during development to catch errors in promise chains.
verbose | Boolean | Default:`false`. Log even more things such as network traffic. Needs `debug: true`
accessToken | String | A signed JWT, telling Hull to automatically log-in a user fetched from your backend. See ["Bring your own users"](#bring-your-own-users)
accessToken | String | A signed JWT, setting identity claims for the current user. See ["Bring your own users"](#bring-your-own-users)
anonymousId | String | Override the auto generated anonymousId. Use the one provided.
sessionId | String | Override the auto generated sessionId. Use the one provided.


## Methods available immediately

```js
Hull.ready(function (hull, me, platform, org) {
console.log('This is your wrapper for Hull', hull);
if (me) { console.log("You're connected, and here's your user:", me); }
Hull.ready(function () {
console.log('This is your wrapper for Hull', Hull);
});

Hull.on('hull.ready', function (hull, me, platform, org) {
console.log('Here you go!');
});

Hull.on('hull.ships.ready', function () {
console.log('Connectors are available in page');
});
```

### `Hull.ready(fn)`

Use `Hull.ready()` to call a function as soon as `hull.js` is
initialized. If you call the function after the initialization is
done, the function is called immediately. Inside [Connectors](/docs/apps/ships), You will probably use `Hull.onEmbed()` instead.
done, the function is called immediately.

`Hull.ready()` can also be used as a promise like this:

```js
Hull.ready().then(({ hull, me, app, org }) => {
console.log('All good', me.name)
Hull.ready().then(() => {
console.log('All good')
});
```

Expand Down Expand Up @@ -129,14 +126,10 @@ These methods are available right away, even before <code>Hull.init()</code> is
window.hullAsyncInit = function(hull){
console.log('Hull Async Init', hull),

hull.on('hull.ready', function(hull, user, app, org) {
hull.on('hull.ready', function(hull) {
console.log('Hull Ready from event')
});
hull.on('hull.ships.ready', function() {
console.log('Hull Ships Ready');
});

hull.ready(function(hull, user, app, org) {
hull.ready(function(hull) {
console.log('Hull Ready!');
});
}
Expand Down Expand Up @@ -168,13 +161,6 @@ To increase security, when identifying users as they use your product, we need y

You can then pass it to Hull to identify the user.[ Here's an article explaining how to generate this token](https://www.hull.io/docs/reference/identity_resolution/)

> Log the user in with a token

```js
const user = await Hull.login({ access_token: SIGNED_JSON_WEB_TOKEN_FROM_BACKEND });
//User Logged in with Hull Access Token
```

> Or during initialization:

```js
Expand All @@ -198,42 +184,6 @@ Hull.init({

If you create a Hull access token (jwt) on the server, you can pass it and we'll log the user in for you. This is used in the [Bring your own users scenario](/docs/users/byou) where either have created in advance or are creating JWT access tokens on the fly for your users.

## Clearing Identifiers

### `Hull.logout()`
Logs the current User out.

```js
Hull.logout().then(function() {
console.log('Goodbye');
}).catch(function(err){
console.log('Something happened', err);
});

```

## Getting the current User's profile

### `Hull.currentUser()`

When a User is currently logged in, `Hull.currentUser()` returns the current User as an object literal. Otherwise, it returns `false`.

> Example Response

```json
{
"id": "50f5768ce78fa367da000001",
"updated_at": "2015-11-19T11:04:28Z",
"created_at": "2013-01-15T15:32:28Z",
"name": "Firstname lastname",
"username": null,
"first_name": "Firstname",
"last_name": "lastname",
"description": null,
"email": "user@host.com",
[...]
}
```

## Getting the current configuration

Expand Down Expand Up @@ -268,8 +218,6 @@ Hull.alias("intercom:"+visitorID)

# Capturing User Attributes

Capturing User Attributes

## `Hull.traits(attributes)`

The `traits` method lets you record Attributes for a given user.
Expand Down Expand Up @@ -453,8 +401,6 @@ You subscribe to them with the `Hull.on()` method:
Event Name | Description | Arguments
-----------|-------------|----------
`hull.ready` | `hull.js` has finished loading. | `Hull`, `me`, `app`, `org`
`hull.ships.ready` | Connectors are loaded. | nothing
`hull.user.update` | User updated any property | `me`
`hull.track` | `Hull.track()` called. | `properties`
`hull.traits` | `Hull.traits()` called. | `event`

Expand Down Expand Up @@ -529,8 +475,6 @@ hull.utils.uuid()
```




# Forwarding data to other services

The Hull library offers a simple way to forward data that you capture to other services. To do so, simply subscribe to it's Event Bus and call your other trackers from there:
Expand Down Expand Up @@ -567,8 +511,6 @@ Hull.on('hull.traits', function(attributes) {
Event Name | Description | Arguments
-----------|-------------|----------
`hull.ready` | `hull.js` has finished loading. | `Hull`, `me`, `app`, `org`
`hull.ships.ready` | Connectors are loaded. | nothing
`hull.user.update` | User updated any property | `me`
`hull.track` | `Hull.track()` called. | `properties`
`hull.traits` | `Hull.traits()` called. | `event`

Expand Down Expand Up @@ -626,77 +568,3 @@ See [https://github.com/asyncly/EventEmitter2](https://github.com/asyncly/EventE
- `Hull.offAny()`
- `Hull.once()`
- `Hull.many()`


# Embedding Connectors in the page

Some connectors can inject code in the page, by having Hull.js inject their own Javascript in the page. When used from a [Connectors](/docs/apps/ships), Hull.js exposes additional methods to help you manage connectors.

## Booting a connector

Connectors can deploy JS code to your page, and expose settings in your dashboard you can use to configure them. Checkout [The docs on Client-side connectors](http://www.hull.io/docs/apps/ships#client-side) to learn more about what is available.

```js
Hull.onEmbed(function(rootNode, deployment, hull) {
console.log('Hello, i am a Connector and i just started');
console.log('Here is my root element : ', rootNode);
console.log('and here is my environment: ', deployment);

hull.track("event",{ parameters }); //GOOD -> we're using the local hull instance
Hull.track("event",{ parameters }) //BAD -> we're referring to the global instance of hull, which is less safe.

});
```

```javascript
const deployment = {
ship: {} //the connector's settings,
platform: {} //the platform's settings,

}
```

<aside>
The `deployment` object will contain the data you need, including the connector's public settings:
</aside>


### `Hull.onEmbed(callback)`
Checkout [Booting your application](/docs/apps/ships#booting-your-application) in the Connectors documentation for more details

## Disabling Connectors Automatic embedding

```html
<script
id="hull-js-sdk"
data-embed="false"
data-platform-id="54feb3b0574f8c7692000cfa"
data-org-url="https://hull-demos.hullapp.io"
src="https://js.hull.io/0.10.0/hull.js.gz"></script>
```

> or

```html
<script src="https://js.hull.io/0.10.0/hull.js.gz"></script>
<script>
Hull.init({
platformId: "YOUR_PLATFORM_ID",
orgUrl: "http://YOUR_ORG.hullapp.io",
embed:false
});
</script>
```

If for some reason you need to prevent auto-embedding of Connectors, you can do so with the `embed=false` parameter.
It will be then up to you to start the connectors, [Here is where the boot usually starts](https://github.com/hull/hull-js/blob/master/src/hull.coffee#L58), see how to start it yourself.

### `Hull.embed()` method

```js
Hull.ready(function(hull, me, platform, org){
Hull.embed(platform.deployments, { reset:false }, callback, errback);
});
```

<aside class="warning">This is an advanced method, if you want to start connectors manually. you're on your own ;p</aside>