Skip to content

Commit 8d60e06

Browse files
stuecclesstueccles
authored
Merge pull request #33 from kianmeng/misc-doc-changes
refactor: misc doc changes
2 parents 6b2461d + 525517c commit 8d60e06

5 files changed

Lines changed: 65 additions & 220 deletions

File tree

‎README.md‎

Lines changed: 42 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,19 @@
1-
# analytics-elixir
1+
# Segment
22

3-
analytics-elixir is a non-official third-party client for [Segment](https://segment.com). Since version `2.0` it supports
3+
<!-- MDOC !-->
4+
5+
[![hex.pm](https://img.shields.io/hexpm/v/segment.svg)](https://hex.pm/packages/segment)
6+
[![hexdocs.pm](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/segment/)
7+
[![hex.pm](https://img.shields.io/hexpm/dt/segment.svg)](https://hex.pm/packages/segment)
8+
[![hex.pm](https://img.shields.io/hexpm/l/segment.svg)](https://hex.pm/packages/segment)
9+
[![github.com](https://img.shields.io/github/last-commit/stueccles/analytics-elixir.svg)](https://github.com/stueccles/analytics-elixir/commits/master)
10+
11+
This is a non-official third-party client for [Segment](https://segment.com). Since version `2.0` it supports
412
batch delivery of events and retries for the API.
513

614
## Installation
715

8-
Add `segment` to your list of dependencies in mix.exs
16+
Add `segment` to your list of dependencies in `mix.exs`.
917

1018
```
1119
def deps do
@@ -15,10 +23,6 @@ def deps do
1523
end
1624
```
1725

18-
## Documentation
19-
20-
Documentation can be be found at [https://hexdocs.pm/segment](https://hexdocs.pm/segment).
21-
2226
## Usage
2327

2428
Start the Segment agent with your write_key from Segment for a HTTP API Server Source
@@ -45,11 +49,8 @@ Segment.Analytics.track(user_id, event, %{property1: "", property2: ""})
4549
or the full way using a struct with all the possible options for the track call
4650

4751
```elixir
48-
%Segment.Analytics.Track{ userId: "sdsds",
49-
event: "eventname",
50-
properties: %{property1: "", property2: ""}
51-
}
52-
|> Segment.Analytics.track
52+
%Segment.Analytics.Track{userId: "sdsds", event: "eventname", properties: %{property1: "", property2: ""}}
53+
|> Segment.Analytics.track
5354
```
5455

5556
### Identify
@@ -58,13 +59,11 @@ or the full way using a struct with all the possible options for the track call
5859
Segment.Analytics.identify(user_id, %{trait1: "", trait2: ""})
5960
```
6061

61-
or the full way using a struct with all the possible options for the identify call
62+
Or the full way using a struct with all the possible options for the identify call.
6263

6364
```elixir
64-
%Segment.Analytics.Identify{ userId: "sdsds",
65-
traits: %{trait1: "", trait2: ""}
66-
}
67-
|> Segment.Analytics.identify
65+
%Segment.Analytics.Identify{userId: "sdsds", traits: %{trait1: "", trait2: ""}}
66+
|> Segment.Analytics.identify
6867
```
6968

7069
### Screen
@@ -73,13 +72,11 @@ or the full way using a struct with all the possible options for the identify ca
7372
Segment.Analytics.screen(user_id, name)
7473
```
7574

76-
or the full way using a struct with all the possible options for the screen call
75+
Or the full way using a struct with all the possible options for the screen call.
7776

7877
```elixir
79-
%Segment.Analytics.Screen{ userId: "sdsds",
80-
name: "dssd"
81-
}
82-
|> Segment.Analytics.screen
78+
%Segment.Analytics.Screen{userId: "sdsds", name: "dssd"}
79+
|> Segment.Analytics.screen
8380
```
8481

8582
### Alias
@@ -88,13 +85,11 @@ or the full way using a struct with all the possible options for the screen call
8885
Segment.Analytics.alias(user_id, previous_id)
8986
```
9087

91-
or the full way using a struct with all the possible options for the alias call
88+
Or the full way using a struct with all the possible options for the alias call.
9289

9390
```elixir
94-
%Segment.Analytics.Alias{ userId: "sdsds",
95-
previousId: "dssd"
96-
}
97-
|> Segment.Analytics.alias
91+
%Segment.Analytics.Alias{userId: "sdsds", previousId: "dssd"}
92+
|> Segment.Analytics.alias
9893
```
9994

10095
### Group
@@ -103,13 +98,11 @@ or the full way using a struct with all the possible options for the alias call
10398
Segment.Analytics.group(user_id, group_id)
10499
```
105100

106-
or the full way using a struct with all the possible options for the group call
101+
Or the full way using a struct with all the possible options for the group call.
107102

108103
```elixir
109-
%Segment.Analytics.Group{ userId: "sdsds",
110-
groupId: "dssd"
111-
}
112-
|> Segment.Analytics.group
104+
%Segment.Analytics.Group{userId: "sdsds", groupId: "dssd"}
105+
|> Segment.Analytics.group
113106
```
114107

115108
### Page
@@ -118,13 +111,11 @@ or the full way using a struct with all the possible options for the group call
118111
Segment.Analytics.page(user_id, name)
119112
```
120113

121-
or the full way using a struct with all the possible options for the page call
114+
Or the full way using a struct with all the possible options for the page call.
122115

123116
```elixir
124-
%Segment.Analytics.Page{ userId: "sdsds",
125-
name: "dssd"
126-
}
127-
|> Segment.Analytics.page
117+
%Segment.Analytics.Page{userId: "sdsds", name: "dssd"}
118+
|> Segment.Analytics.page
128119
```
129120

130121
### Using the Segment Context
@@ -133,43 +124,42 @@ If you want to set the Context manually you should create a `Segment.Analytics.C
133124

134125
```elixir
135126
context = Segment.Analytics.Context.new(%{active: false})
136-
137127
Segment.Analytics.track(user_id, event, %{property1: "", property2: ""}, context)
138128
```
139129

140130
## Configuration
141131

142132
The library has a number of configuration options you can use to overwrite default values and behaviours
143133

144-
- `config :segment, :sender_impl` Allows selection of a sender implementation. At the moment this defaults to `Segment.Analytics.Batcher` which will send all events in batch. Change this value to `Segment.Analytics.Sender` to have all messages sent immediately (asyncronously)
134+
- `config :segment, :sender_impl` Allows selection of a sender implementation. At the moment this defaults to `Segment.Analytics.Batcher` which will send all events in batch. Change this value to `Segment.Analytics.Sender` to have all messages sent immediately (asynchronously)
145135
- `config :segment, :max_batch_size` The maximum batch size of messages that will be sent to Segment at one time. Default value is 100.
146136
- `config :segment, :batch_every_ms` The time (in ms) between every batch request. Default value is 2000 (2 seconds)
147137
- `config :segment, :retry_attempts` The number of times to retry sending against the segment API. Default value is 3
148138
- `config :segment, :retry_expiry` The maximum time (in ms) spent retrying. Default value is 10000 (10 seconds)
149139
- `config :segment, :retry_start` The time (in ms) to start the first retry. Default value is 100
150-
- `config :segment, :send_to_http` If set to `false`, the libray will override the Tesla Adapter implementation to only log segment calls to `debug` but not make any actual API calls. This can be useful if you want to switch off Segment for test or dev. Default value is true
140+
- `config :segment, :send_to_http` If set to `false`, the library will override the Tesla Adapter implementation to only log segment calls to `debug` but not make any actual API calls. This can be useful if you want to switch off Segment for test or dev. Default value is true
151141
- `config :segment, :tesla, :adapter` This config option allows for overriding the HTTP Adapter for Tesla (which the library defaults to Hackney).This can be useful if you prefer something else, or want to mock the adapter for testing.
152142
- `config :segment, api_url: "https://self-hosted-segment-api.com/v1/"` The Segment-compatible API endpoint that will receive your events. Defaults to `https://api.segment.io/v1/`. This setting is only useful if you are using a Segment-compatible alternative API like [Rudderstack](https://rudderstack.com/).
153143

154144
## Usage in Phoenix
155145

156146
This is how I add to a Phoenix project (may not be your preferred way)
157147

158-
1. Add the following to deps section of your mix.exs: `{:segment, "~> 0.2.0"}`
159-
and then `mix deps.get`
160-
2. Add a config variable for your write_key (you may want to make this load from ENV)
161-
ie.
148+
1. Add the following to deps section of your mix.exs: `{:segment, "~> 0.2.0"}`
149+
and then `mix deps.get`
150+
2. Add a config variable for your write_key (you may want to make this load from ENV)
151+
ie.
162152

163-
```elixir
164-
config :segment,
165-
write_key: "2iFFnRsCfi"
166-
```
153+
```elixir
154+
config :segment,
155+
write_key: "2iFFnRsCfi"
156+
```
167157

168-
3. Start the Segment GenServer in the supervised children list. In `application.ex` add to the children list:
158+
3. Start the Segment GenServer in the supervised children list. In `application.ex` add to the children list:
169159

170-
```elixir
171-
{Segment, Application.get_env(:segment, :write_key)}
172-
```
160+
```elixir
161+
{Segment, Application.get_env(:segment, :write_key)}
162+
```
173163

174164
## Running tests
175165

‎lib/segment.ex‎

Lines changed: 4 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -1,153 +1,9 @@
11
defmodule Segment do
2-
@moduledoc """
3-
The Segement analytics-elixir is a non-official third-party client for [Segment](https://segment.com). Since version `0.2.0` it supports
4-
batch delivery of events and retries for the API.
2+
@moduledoc "README.md"
3+
|> File.read!()
4+
|> String.split("<!-- MDOC !-->")
5+
|> Enum.fetch!(1)
56

6-
## Installation
7-
8-
Add `segment` to your list of dependencies in mix.exs
9-
10-
```
11-
def deps do
12-
[
13-
{:segment, "~> 0.2.0"}
14-
]
15-
end
16-
```
17-
18-
## Documentation
19-
20-
Documentation can be be found at [https://hexdocs.pm/segment](https://hexdocs.pm/segment).
21-
22-
## Usage
23-
24-
Start the Segment agent with your write_key from Segment for a HTTP API Server Source
25-
```elixir
26-
Segment.start_link("YOUR_WRITE_KEY")
27-
```
28-
There are then two ways to call the different methods on the API.
29-
A basic way through `Segment.Analytics` functions with either the full event Struct
30-
or some helper methods (also allowing Context and Integrations to be set manually).
31-
32-
This way will use the defined GenServer implementation such as `Segment.Analytics.Batcher` which will
33-
queue and batch events to Segment.
34-
35-
The other way is to drop down lower and use `Segment.Http` `send` and `batch` directly. This will require first creating a `client` with `Segment.Http.client/1`/`Segment.Http.client/2`
36-
37-
### Track
38-
```elixir
39-
Segment.Analytics.track(user_id, event, %{property1: "", property2: ""})
40-
```
41-
or the full way using a struct with all the possible options for the track call
42-
```elixir
43-
%Segment.Analytics.Track{ userId: "sdsds",
44-
event: "eventname",
45-
properties: %{property1: "", property2: ""}
46-
}
47-
|> Segment.Analytics.track
48-
```
49-
50-
### Identify
51-
```elixir
52-
Segment.Analytics.identify(user_id, %{trait1: "", trait2: ""})
53-
```
54-
or the full way using a struct with all the possible options for the identify call
55-
```elixir
56-
%Segment.Analytics.Identify{ userId: "sdsds",
57-
traits: %{trait1: "", trait2: ""}
58-
}
59-
|> Segment.Analytics.identify
60-
```
61-
62-
### Screen
63-
```elixir
64-
Segment.Analytics.screen(user_id, name)
65-
```
66-
or the full way using a struct with all the possible options for the screen call
67-
```elixir
68-
%Segment.Analytics.Screen{ userId: "sdsds",
69-
name: "dssd"
70-
}
71-
|> Segment.Analytics.screen
72-
```
73-
74-
### Alias
75-
```elixir
76-
Segment.Analytics.alias(user_id, previous_id)
77-
```
78-
or the full way using a struct with all the possible options for the alias call
79-
```elixir
80-
%Segment.Analytics.Alias{ userId: "sdsds",
81-
previousId: "dssd"
82-
}
83-
|> Segment.Analytics.alias
84-
```
85-
86-
### Group
87-
```elixir
88-
Segment.Analytics.group(user_id, group_id)
89-
```
90-
or the full way using a struct with all the possible options for the group call
91-
```elixir
92-
%Segment.Analytics.Group{ userId: "sdsds",
93-
groupId: "dssd"
94-
}
95-
|> Segment.Analytics.group
96-
```
97-
98-
### Page
99-
```elixir
100-
Segment.Analytics.page(user_id, name)
101-
```
102-
or the full way using a struct with all the possible options for the page call
103-
```elixir
104-
%Segment.Analytics.Page{ userId: "sdsds",
105-
name: "dssd"
106-
}
107-
|> Segment.Analytics.page
108-
```
109-
110-
111-
### Using the Segment Context
112-
113-
If you want to set the Context manually you should create a `Segment.Analytics.Context` struct with `Segment.Analytics.Context.new/1`
114-
115-
```elixir
116-
context = Segment.Analytics.Context.new(%{active: false})
117-
118-
Segment.Analytics.track(user_id, event, %{property1: "", property2: ""}, context)
119-
```
120-
121-
## Configuration
122-
123-
The library has a number of configuration options you can use to overwrite default values and behaviours
124-
125-
* `config :segment, :sender_impl` Allows selection of a sender implementation. At the moment this defaults to `Segment.Analytics.Batcher` which will send all events in batch. Change this value to `Segment.Analytics.Sender` to have all messages sent immediately (asyncronously)
126-
* `config :segment, :max_batch_size` The maximum batch size of messages that will be sent to Segment at one time. Default value is 100.
127-
* `config :segment, :batch_every_ms` The time (in ms) between every batch request. Default value is 2000 (2 seconds)
128-
* `config :segment, :retry_attempts` The number of times to retry sending against the segment API. Default value is 3
129-
* `config :segment, :retry_expiry` The maximum time (in ms) spent retrying. Default value is 10000 (10 seconds)
130-
* `config :segment, :retry_start` The time (in ms) to start the first retry. Default value is 100
131-
* `config :segment, :send_to_http` If set to `false`, the libray will override the Tesla Adapter implementation to only log segment calls to `debug` but not make any actual API calls. This can be useful if you want to switch off Segment for test or dev. Default value is true
132-
* `config :segment, :tesla, :adapter` This config option allows for overriding the HTTP Adapter for Tesla (which the library defaults to Hackney).This can be useful if you prefer something else, or want to mock the adapter for testing.
133-
134-
## Usage in Phoenix
135-
136-
This is how I add to a Phoenix project (may not be your preferred way)
137-
138-
1. Add the following to deps section of your mix.exs: `{:segment, "~> 0.2.0"}`
139-
and then `mix deps.get`
140-
2. Add a config variable for your write_key (you may want to make this load from ENV)
141-
ie.
142-
```elixir
143-
config :segment,
144-
write_key: "2iFFnRsCfi"
145-
```
146-
3. Start the Segment GenServer in the supervised children list. In `application.ex` add to the children list:
147-
```elixir
148-
{Segment, Application.get_env(:segment, :write_key)}
149-
```
150-
"""
1517
@type segment_event ::
1528
Segment.Analytics.Track.t()
1539
| Segment.Analytics.Identify.t()

‎lib/segment/client/http.ex‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,9 @@ defmodule Segment.Http do
2525
* `config :segment, :retry_attempts` The number of times to retry sending against the segment API. Default value is 3
2626
* `config :segment, :retry_expiry` The maximum time (in ms) spent retrying. Default value is 10000 (10 seconds)
2727
* `config :segment, :retry_start` The time (in ms) to start the first retry. Default value is 100
28-
* `config :segment, :send_to_http` If set to `false`, the libray will override the Tesla Adapter implementation to only log segment calls to `debug` but not make any actual API calls. This can be useful if you want to switch off Segment for test or dev. Default value is true
28+
* `config :segment, :send_to_http` If set to `false`, the library will override the Tesla Adapter implementation to only log segment calls to `debug` but not make any actual API calls. This can be useful if you want to switch off Segment for test or dev. Default value is true
2929
30-
The retry uses a linear back-off strategy when retring the Segment API.
30+
The retry uses a linear back-off strategy when retrying the Segment API.
3131
3232
Additionally a different Tesla Adapter can be used if you want to use something other than Hackney.
3333

‎lib/segment/sender.ex‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ defmodule Segment.Analytics.Sender do
33
The `Segment.Analytics.Sender` service implementation is an alternative to the default Batcher to send every event as it is called.
44
The HTTP call is made with an async `Task` to not block the GenServer. This will not guarantee ordering.
55
6-
The `Segment.Analytics.Batcher` should be preferred in production but this module will emulate the implementaiton of the original library if
6+
The `Segment.Analytics.Batcher` should be preferred in production but this module will emulate the implementation of the original library if
77
you need that or need events to be as real-time as possible.
88
"""
99
use GenServer
@@ -31,7 +31,7 @@ defmodule Segment.Analytics.Sender do
3131
# client
3232
@doc """
3333
Make a call to Segment with an event. Should be of type `Track, Identify, Screen, Alias, Group or Page`.
34-
This event will be sent immediately and asyncronously
34+
This event will be sent immediately and asynchronously
3535
"""
3636
@spec call(Segment.segment_event()) :: :ok
3737
def call(%{__struct__: mod} = event)

0 commit comments

Comments
 (0)