Pathway
Pathway is a HTTP client library for the Trak.io REST API.
Trak.io is a service that allows you to save details about your users (people) and their behaviour (events). The service can take in different types of customer data, such as feature usage, payments, support tickets and email history, and then automatically segment users based on that data.
The Trak.io API is made up of alias, annotate, identify, page_view and
track actions. These actions are available in the client as functions with
the same names.
Configuration
The client can be configured in the usual way by adding these settings to your
config.exs file:
config :pathway,
apikey: "a Trak.io apikey",
timeout: 3000
retries: 2Only the apikey is a required configuration property. The other properties are initialised with default values.
Example
The client creates a connection to the Trak.io API server on
Pathway.Client.start_link. The Pathway.Client is a GenServer whose
process is linked to the connection’s pid. If the connection dies the
Pathway.Client will also die. For this reason it’s recommended to
supervise the client like so:
# within your Application start callback
children = [
worker(Pathway.Client, [[]])
]
opts = [strategy: :one_for_one, name: YourApp.Supervisor]
Supervisor.start_link(children, opts)Alternatively, if you don’t want to supervise the client or you’re experimenting in the iex console you can manually start the client like so:
Pathway.Client.start_link()Once the client has been initialised you can start making requests to the Trak.io API. For example, let’s assume you have a signup function that gets called when a user signs up, this would be a good opportunity to create an identity for the new user.
user = %{name: "Some User", email: "user@email.com", id: "a new user's ID"}
Pathway.identity(user.id, user)
# you might also want to send an event for the action
Pathway.track(user.id, "user signed up")NOTE: This client is a work-in-progress, any feedback and bug reports are welcome.
Summary
| alias!(distinct_id, alias) | |
| alias(distinct_id, alias) | Alias is how you set additional distinct ids for a person |
| annotate!(event, properties \\ %{}, channel \\ nil) | |
| annotate(event, properties \\ %{}, channel \\ nil) | Annotate is a way of recording system wide events that affect everyone |
| identify!(distinct_id, properties \\ %{}) | |
| identify(distinct_id, properties \\ %{}) | Identify is how you send Trak.io properties about a person like email, name, account type, age, etc |
| track!(distinct_id, event, properties \\ %{}, channel \\ "web_site", company_id \\ nil) | |
| track(distinct_id, event, properties \\ %{}, channel \\ "web_site", company_id \\ nil) | Track is how you record the actions people perform |
Functions
Specs:
Alias is how you set additional distinct ids for a person.
This is useful if you initially use Trak.io’s automatically generated distinct id to identify or track a person but then they login or register and you want to identify them by their email address or your application’s id for them.
Example
iex> Pathway.alias("some ID", ["person's other ID"])
{:ok, %{"status" => "success"}}Annotate is a way of recording system wide events that affect everyone.
Annotations are similar to events except they are not associated with any one person.
Examples
iex> Pathway.annotate("Deployed update")
{:ok, %{"status" => "success"}}
iex> Pathway.annotate("Deployed Update", %{commit: "5ab430d"}, "Documentation")
{:ok, %{"status" => "success"}}Identify is how you send Trak.io properties about a person like email, name, account type, age, etc.
Example
iex> Pathway.identify("some ID", %{name: "A name", email: "email@app.com"})
{:ok, %{"status" => "success"}}Track is how you record the actions people perform.
You can also record properties specific to those actions. For a “Purchased shirt” event, you might record properties like revenue, size, etc.
Examples
iex> Pathway.track("12346789", "Page view", %{}, "web site", "acme_ltd")
{:ok, %{"status" => "success"}}