{"id":17133818,"url":"https://github.com/jereinhardt/lear","last_synced_at":"2025-03-24T05:44:32.392Z","repository":{"id":138565301,"uuid":"246903216","full_name":"jereinhardt/lear","owner":"jereinhardt","description":"Automated data tracking for plug-based Elixir applications","archived":false,"fork":false,"pushed_at":"2020-03-12T20:40:38.000Z","size":16,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-29T11:33:34.647Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jereinhardt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-12T18:20:55.000Z","updated_at":"2020-03-12T20:40:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"60b01872-3d1f-4186-800d-0afd009a5c9d","html_url":"https://github.com/jereinhardt/lear","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jereinhardt%2Flear","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jereinhardt%2Flear/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jereinhardt%2Flear/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jereinhardt%2Flear/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jereinhardt","download_url":"https://codeload.github.com/jereinhardt/lear/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245217789,"owners_count":20579297,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-14T19:43:06.656Z","updated_at":"2025-03-24T05:44:32.372Z","avatar_url":"https://github.com/jereinhardt.png","language":"Elixir","readme":"# Lear\n\nLear is an automated data-tracking library for plug-based Elixir applications.\n\nLear tracks user sessions, server requests, and other events and saves that\ninformation in a persistent data store of your choosing.\n\n## What Gets Tracked\n\nLear breaks tracking data down into two categories: Sessions and Events. Events\nare individual actions taken by users. Sessions are a persistent chain of \ninteractions made by a single user in a single sitting, and are made up of many\nevents.\n\nLear automatically tracks certain data related to Sessions.  Session\ndetails are automatically parsed from the connection.  While that data cannot be\noverwritten, you can track additional properties from the connection (see\n[configuration](#configuration) for more details.)\n\n## Installation\n\nIf [available in Hex](https://hex.pm/docs/publish), the package can be installed\nby adding `lear` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:lear, \"~\u003e 0.1.0\"}\n  ]\nend\n```\n\nIn order to use Lear, you must first create an implementation module that will \ninclude Lear's functionality and act as your main API for saving data.  To do \nthis, create a module that uses `Lear` and implements any functions necessary \nfor data tracking within your application (see [configuration](#configuration) \nfor more details).  At the very least, you should implement a \n`current_user_resource/1` function.\n\n```elixir\ndefmodule MyApp.Lear do\n  use Lear, store: MyApp.LearStore\n\n  def current_user_resource(conn) do\n    case conn.assigns do\n      %{current_user: user} -\u003e {:ok, user.id}\n      _ -\u003e {:error, nil}\n    end\n  end\nend\n```\n\nOnce you've defined your implementation module, you will need to include Lear's\nplugs within your pipeline.  There are two ways to accomplish this.\n\nThe easiest way is to include Lear's default plug within your pipeline:\n\n```elixir\nplug Lear.Plug.Pipeline, module: MyApp.Lear\n```\n\nThis will automatically track sessions and server requests within the plug \npipeline.\n\nYou can also define your own Lear plug for more control over tracking data.  To\naccomplish this, you must create a module that uses `Lear.Plug.Pipeline`, and \ninclude any necessary options as arguments.\n\n```elixir\ndefmodule MyApp.Lear.Pipeline do\n  use Lear.Plug.Pipeline, module: MyApp.Lear\n\n  plug Lear.Plug.TrackSession\n  plug Lear.Plug.TrackRequest\n  plug :track_utm_requests\n\n  def track_utm_requests(conn, _opts) do\n    utm_params =\n      conn.query_params\n      |\u003e Enum.filter(fn {k, _} -\u003e String.starts_with?(k, \"utm\") end)\n      |\u003e Map.new()\n    if Map.keys(utm_params) |\u003e Enum.any?() do\n      MyApp.Lear.track(conn, \"utm request\", utm_params)\n    end\n\n    conn\n  end\nend\n```\n\nYou can then include your custom module within your pipeline.\n\n```elixir\nplug MayApp.Lear.Pipeline\n```\n\n## Configuration\n\n### Configuring your Implementation Module\n\nWhen creating your implementation module, you can provide options to `use Lear` \nto configure it's behaviour.\n\n* `:store` - the module that acts as the main API for interacting with your \napplication's persistent data store.  See [stores](#stores) for more details.\n* `:session_cookie_name` - (optional) the name of the cookie that will hold the\ncurrent session id.\n\nYou can further configure your implementation module by defining optional \ncallbacks to control what details are tracked.\n\n`current_user_resource/1` - Returns a tuple with the id of the current user, or\n{:error, nil} if no id is present.\n\n`request_properties/1` - returns a map of properties for each request that will \nbe saved.\n\n`session_properties/1` - returns a map of properties that will be saved as\nadditional session details.\n\n### Configuring your Pipeline\n\nWhether you are using Lear's default pipeline, it's individual plugs, or \ncreating your own pipeline, all of Lear's plug's require a `:module` option to\nbe given to point to your application's implementation module.\n\nLear's individual plugs may accept other options as well for further \ncustomization.  See their documentation for further details.\n\n## Stores\n\nA Store is a module that acts as an API for persisting tracking data.  For most\ncases, you will want to save data to the database.  If you application uses\nEcto, like most Phoenix applications, it is recommended that you use [LearEcto](https://github.com/jereinhardt/lear_ecto) \nas your store.\n\n## Documentation\n\nDocumentation can be found at [https://hexdocs.pm/lear](https://hexdocs.pm/lear).\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjereinhardt%2Flear","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjereinhardt%2Flear","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjereinhardt%2Flear/lists"}