Skip to content

feat(): Introduce the article page #119

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

Merged
merged 3 commits into from
Oct 14, 2019
Merged

feat(): Introduce the article page #119

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
054934a
feat(): Introduce the article page
Oct 14, 2019
5685f87
fix(): Add props to includes
Oct 14, 2019
d0dca7d
fix(): Reset top margin to the first element inside the markdown content
Oct 14, 2019
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
2 changes: 1 addition & 1 deletion src/_includes/components/avatar.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{% assign contributor = page.contributors | first %}
{% assign contributor = include.contributors | first %}
{% assign day = contributor.date | date: "%-d" %}

{% if contributor %}
Expand Down
4 changes: 3 additions & 1 deletion src/_includes/components/media-icon.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
<div class="media-icon">
<a class="media-icon__inner" href="{{ site.baseurl }}{{ include.href }}">
<span class="media-icon__icon">
{% include icons/{{ include.icon }} %}
{% if include.icon %}
{% include icons/{{ include.icon }} %}
{% endif %}
</span>

<h5 class="media-icon__heading">{{ include.title }}</h5>
Expand Down
2 changes: 1 addition & 1 deletion src/_includes/components/related.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{% for related_url in page.related %}
{% for related_url in include.items %}
{% assign subpage = site.pages | where: 'url', related_url | first %}

{% include components/media-icon.html variant="related" href=subpage.url icon=subpage.icon title=subpage.title content=subpage.excerpt %}
Expand Down
21 changes: 21 additions & 0 deletions src/_layouts/page.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,27 @@ <h1 id="{{ page.title | downcase }}" class="page__heading">
{{ content }}
</div>

{% if page.faq %}
<hr>

<h2>FAQ</h2>

{% include components/faq.html items=page.faq %}
{% endif %}


{% if page.contributors %}
{% include components/avatar.html contributors=page.contributors %}
{% endif %}

{% if page.related %}
<hr>

<h2>Further reading</h2>

{% include components/related.html items=page.related %}
{% endif %}

<hr>

{% include components/feedback.html %}
Expand Down
4 changes: 4 additions & 0 deletions src/_sass/components/_markdown.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,4 +238,8 @@
& > table {
margin-top: 24px;
}

& > *:first-child {
margin-top: 0;
}
}
16 changes: 0 additions & 16 deletions src/connections/sources/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,19 +199,3 @@ We’d love to know what other sources of data you’d like to analyze. Please [
## Visual Tagger (Beta)

[Getting started with Segment Visual Tagger](/docs/sources/visual-tagger)

---

## FAQ

{% include components/faq.html items=page.faq %}

<br>

{% include components/avatar.html %}

---

## Further reading

{% include components/related.html %}
199 changes: 58 additions & 141 deletions src/connections/spec/identify.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,19 @@
---
title: 'Spec: Identify'
sidebar: Identify
contributors:
- name: Paul Mccall
position: Lead Developer
image_path: paul-mccall.png
date: 23.08.2019
related:
- "/connections/sources/catalog/"
- "/connections/sources/faq/"
- "/connections/sources/guides/"
---

## Identify

`identify` lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about them like their email, name, etc.

Our recommendation for when and how often you should call identify is as follows:
Expand Down Expand Up @@ -39,79 +50,59 @@ And here's the corresponding Javascript event that would generate the above payl

```js
analytics.identify("97980cfea0067", {
name: "Peter Gibbons",
email: "peter@initech.com",
plan: "premium",
name: "Peter Gibbons",
email: "peter@initech.com",
plan: "premium",
logins: 5
});
```

Beyond the common fields, an `identify` call has the following fields:

<table>
<tr>
<th>**Field**</th>
<th>**Type**</th>
<th>**Description**</th>
</tr>
{% include content/spec-field-identify-traits.md %}
{% include content/spec-field-user-id.md %}
</table>
| Field | Type | Description |
| --- | --- | --- |
| `traits` <br> optional | Object | Free-form dictionary of traits of the user, like `email` or `name`. <br> See the [Traits field docs](/docs/spec/identify#traits) |
| `userId` <br> optional/required | String | Unique identifier for the user in your database. A userId or an anonymousId is required.<br> See the [Identities docs](/docs/spec/identify#identities) for more detail. |

{% include components/alert.html type="success" content="Your message has been sent successfully. This is a paragraph showing alert box. Indicates a successful or positive action." %}

## Example

Here's a complete example of an `identify` call:

```json
{
"anonymousId": "507f191e810c19729de860ea",
"channel": "browser",
"context": {
"ip": "8.8.8.8",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36"
},
"integrations": {
"All": false,
"Mixpanel": true,
"Salesforce": true
},
"messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
"receivedAt": "2015-02-23T22:28:55.387Z",
"sentAt": "2015-02-23T22:28:55.111Z",
"timestamp": "2015-02-23T22:28:55.111Z",
"type": "identify",
"traits": {
"name": "Peter Gibbons",
"email": "peter@initech.com",
"plan": "premium",
"logins": 5,
"address": {
"street": "6th St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94103",
"country": "USA"
}
"logins": 5
},
"type": "identify",
"userId": "97980cfea0067",
"version": "1.1"
"userId": "97980cfea0067"
}
```

## Identities

The `identify` call specifies a customer identity that you can reference across the customer's whole lifetime. **Every `identify` call must have a [User ID](/docs/spec/identify#user-id) or an [Anonymous ID](/docs/spec/identify#anonymous-id)**, depending on how much you know about the user in question.

{% include components/alert.html type="info" content="Please read the comments carefully. This is a paragraph showing information box. Indicates a neutral informative change or action." %}

### Anonymous ID

There are certain cases where you don't actually know who the user is according to your database, but you still want to be able to tie them to traits, events or page views. For example, you may not know who a user is when tracking newsletter signups or anonymous page views.

In these cases, you should use an Anonymous ID.

{% include components/alert.html type="warning" content="There was a problem with your network connection. Indicates a warning that might need attention. This is a paragraph showing warning box." %}

The Anonymous ID can be any pseudo-unique identifier. For example, on your servers you can use a session id. If you don't have any readily available identifier, you can always generate a new random one—we recommend [UUIDs](http://en.wikipedia.org/wiki/Universally_unique_identifier).

**Note:** Our [browser and mobile libraries](/docs/sources/) **automatically** use Anonymous IDs under the covers to keep track of users as they navigate around your website or app, so you don't need to worry about them when using those libraries.
{% capture AnonymousID_note %}
Our [browser and mobile libraries](/docs/sources/) **automatically** use Anonymous IDs under the covers to keep track of users as they navigate around your website or app, so you don’t need to worry about them when using those libraries.
{% endcapture %}
{% include components/note.html content=AnonymousID_note %}

### User ID

Expand All @@ -123,6 +114,8 @@ We recommend using database IDs instead of simple email addresses or usernames,

**Instead of using an email address or a username as a User ID, send them along as [traits](/docs/spec/identify#traits).**

![](../images/user-id.png)

## Traits

Traits are pieces of information you know about a user that are included in an `identify` call. These could be demographics like `age` or `gender`, account-specific like `plan`, or even things like whether a user has seen a particular A/B test variation. Up to you!
Expand All @@ -133,105 +126,29 @@ You should **only use reserved traits for their intended meaning**.

Reserved traits we've standardized:

<table>
<tr>
<th>**Trait**</th>
<th>**Type**</th>
<th>**Description**</th>
</tr>
<tr>
<td>`address`</td>
<td>Object</td>
<td>Street address of a user optionally containing: `city`, `country`, `postalCode`, `state` or `street`</td>
</tr>
<tr>
<td>`age`</td>
<td>Number</td>
<td>Age of a user</td>
</tr>
<tr>
<td>`avatar`</td>
<td>String</td>
<td>URL to an avatar image for the user</td>
</tr>
<tr>
<td>`birthday`</td>
<td>Date</td>
<td>User's birthday</td>
</tr>
<tr>
<td>`company`</td>
<td>Object</td>
<td>Company the user represents, optionally containing: `name` (a String), `id` (a String or Number), `industry` (a String), `employee_count` (a Number) or `plan` (a String)</td>
</tr>
<tr>
<td>`createdAt`</td>
<td>Date</td>
<td>Date the user's account was first created
<p>We recommend [ISO-8601](http://en.wikipedia.org/wiki/ISO_8601) date strings.</p></td>
</tr>
<tr>
<td>`description`</td>
<td>String</td>
<td>Description of the user</td>
</tr>
<tr>
<td>`email`</td>
<td>String</td>
<td>Email address of a user</td>
</tr>
<tr>
<td>`firstName`</td>
<td>String</td>
<td>First name of a user</td>
</tr>
<tr>
<td>`gender`</td>
<td>String</td>
<td>Gender of a user</td>
</tr>
<tr>
<td>`id`</td>
<td>String</td>
<td>Unique ID in your database for a user</td>
</tr>
<tr>
<td>`lastName`</td>
<td>String</td>
<td>Last name of a user</td>
</tr>
<tr>
<td>`name`</td>
<td>String</td>
<td>Full name of a user
<p> If you only pass a first and last name we'll automatically fill in the full name for you.</p>
</td>
</tr>
<tr>
<td>`phone`</td>
<td>String</td>
<td>Phone number of a user</td>
</tr>
<tr>
<td>`title`</td>
<td>String</td>
<td>Title of a user, usually related to their position at a specific company
<p>Example: "VP of Engineering"</p>
</td>
</tr>
<tr>
<td>`username`</td>
<td>String</td>
<td>User's username
<p> This should be unique to each user, like the usernames of Twitter or GitHub.</p></td>
</tr>
<tr>
<td>`website`</td>
<td>String</td>
<td>Website of a user</td>
</tr>
</table>

**Note:** You might be used to some destinations recognizing special traits by slightly different names. For example, Mixpanel recognizes a `$created` trait when the user's account was first created, while Intercom recognizes the same trait as `created_at` instead. Luckily, you don't have to worry about those inconsistencies. Just pass us `createdAt`. **We’ll handle all of the destination-specific conversions for you automatically.** Same goes for the rest of the reserved traits.

**You can pass these reserved traits using camelCase or snake_case**, so in Javascript you can match the rest of your camel-case code by sending `firstName`, while in Ruby you can match your snake-case code by sending `first_name`. That way the API never seems alien to your code base. Keep in mind that not all destinations support these reserved traits, so sending these traits in camelCase and snake_case can result in two sets of traits in other destinations.
| Trait | Type | Description |
| --- | --- | --- |
| `address` | Object | Street address of a user optionally containing: `city`, `country`, `postalCode`, `state` or `street` |
| `age` | Number | Age of a user |
| `avatar` | String | URL to an avatar image for the user |
| `birthday` | Date | User's birthday |
| `company` | Object | Company the user represents, optionally containing: `name` (a String), `id` (a String or Number), `industry` (a String), `employee_count` (a Number) or `plan` (a String) |
| `createdAt` | Date | Date the user's account was first created <br> We recommend [ISO-8601](http://en.wikipedia.org/wiki/ISO_8601) date strings. |
| `description` | String | Description of the user |
| `email` | String | Email address of a user |
| `firstName` | String | First name of a user |
| `gender` | String | Gender of a user |
| `id` | String | Unique ID in your database for a user |
| `lastName` | String | Last name of a user |
| `name` | String | Full name of a user <br> If you only pass a first and last name we'll automatically fill in the full name for you. |
| `phone` | String | Phone number of a user |
| `title` | String | Title of a user, usually related to their position at a specific company <br> Example: "VP of Engineering" |
| `username` | String | User's username <br> This should be unique to each user, like the usernames of Twitter or GitHub. |
| `website` | String | Website of a user |

{% capture Traits_note %}
You might be used to some destinations recognizing special traits by slightly different names. For example, Mixpanel recognizes a `$created` trait when the user's account was first created, while Intercom recognizes the same trait as `created_at` instead. Luckily, you don't have to worry about those inconsistencies. Just pass us `createdAt`. **We’ll handle all of the destination-specific conversions for you automatically.** Same goes for the rest of the reserved traits.
**You can pass these reserved traits using camelCase or snake_case**, so in Javascript you can match the rest of your camel-case code by sending `firstName`, while in Ruby you can match your snake-case code by sending `first_name`. That way the API never seems alien to your code base. Keep in mind that not all destinations support these reserved traits, so sending these traits in camelCase and snake_case can result in two sets of traits in other destinations.
{% endcapture %}

{% include components/note.html content=Traits_note %}
Binary file added src/connections/spec/images/user-id.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 0 additions & 18 deletions src/styleguide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,12 +97,6 @@ analytics.identify('025pikachu025', {

---

## Avatar

{% include components/avatar.html %}

---

## Media Icons

{% include components/media-icon.html href="#" icon="media/icon-academy.svg" title="Title" content="Lorem ipsum dolor sit amet consectetur, adipisicing elit. Iusto ratione ipsum fugiat nostrum velit iure, molestiae accusamus tempora quos laborum, ex modi illum delectus. Suscipit nesciunt labore nulla numquam excepturi?" %}
Expand Down Expand Up @@ -130,15 +124,3 @@ analytics.identify('025pikachu025', {
{% include components/alert.html type="success" content="This is my sample note." %}
{% include components/alert.html type="warning" content="This is my sample note." %}
{% include components/alert.html type="error" content="This is my sample note." %}

---

## Callout

{% include components/callout.html title="Get started with Segment" content="Segment is the easiest way to integrate your websites & mobile apps data to 250+ analytics and growth tools." %}

---

## FAQ

{% include components/faq.html items=page.faq %}