提供追蹤臨在狀態給程序和頻道。

此行為提供臨在狀態功能，例如提取給定主題的臨在狀態，以及處理在即時發生的加入和離開事件的差異。使用這個模組會定義一個監視程式和一個實作 Phoenix.Tracker 行為的模組，該行為使用 Phoenix.PubSub 廣播追蹤臨在狀態的更新。

如果你只想要使用 Phoenix.Presence 所提供的功能中的某個子集，例如追蹤程序但沒有廣播更新，我們建議你查看 phoenix_pubsub 計畫中的 Phoenix.Tracker 功能。

範例用法

從在你應用程式內定義一個臨在狀態模組開始，該模組使用 Phoenix.Presence 並提供包含你的組態的 :otp_app，以及 :pubsub_server。

defmodule MyAppWeb.Presence do
  use Phoenix.Presence,
    otp_app: :my_app,
    pubsub_server: MyApp.PubSub
end

此 :pubsub_server 必須指向一個在你的應用程式中執行的現有 pubsub 伺服器，對於新的應用程式，此伺服器預設包含在 MyApp.PubSub 中。

接下來，在 lib/my_app/application.ex 的監視程式樹中新增新的監視程式。它必須在 PubSub 子項的後面，端點的前面

children = [
  ...
  {Phoenix.PubSub, name: MyApp.PubSub},
  MyAppWeb.Presence,
  MyAppWeb.Endpoint
]

新增後，就能在加入你的頻道後追蹤臨在狀態

defmodule MyAppWeb.MyChannel do
  use MyAppWeb, :channel
  alias MyAppWeb.Presence

  def join("some:topic", _params, socket) do
    send(self(), :after_join)
    {:ok, assign(socket, :user_id, ...)}
  end

  def handle_info(:after_join, socket) do
    {:ok, _} = Presence.track(socket, socket.assigns.user_id, %{
      online_at: inspect(System.system_time(:second))
    })

    push(socket, "presence_state", Presence.list(socket))
    {:noreply, socket}
  end
end

在上方的範例中，Presence.track 用於註冊此頻道的程序作為一個符有使用者 ID 的 socket 的臨在狀態，並提供一份臨在狀態資料。接下來，socket 的主題的目前臨在狀態資訊會以 "presence_state" 事件推送到用戶端。

最後，臨在狀態的加入和離開事件的差異會在即時發生時以 "presence_diff" 事件傳送給用戶端。差異結構會是 :joins 和 :leaves 的映射，格式如下

%{
  joins: %{"123" => %{metas: [%{status: "away", phx_ref: ...}]}},
  leaves: %{"456" => %{metas: [%{status: "online", phx_ref: ...}]}}
},

請參閱 list/1 瞭解臨在狀態資料結構的詳細資訊。

提取臨在狀態資訊

應該將身分資料最小化，用來儲存較小、暫時性的狀態，例如使用者的「線上」或「離開中」狀態。較詳細資料，例如需要從資料庫取得的使用者詳細資料，可透過覆寫 fetch/2 函式完成。

fetch/2 回呼會在使用 list/1 和每次更新時觸發，並作為一種機制，可以在將資訊廣播給所有頻道訂閱者之前單次擷取身分資訊。這可避免 N 個查詢問題，並提供單一處可將孤立資料擷取分組以延伸身分資料的位置。

此函式必須回傳符合概述的身分資料結構的資料映射表，包含 :metas 金鑰，但可延伸資訊映射表以包含任何其他資訊。例如

def fetch(_topic, presences) do
  users = presences |> Map.keys() |> Accounts.get_users_map()

  for {key, %{metas: metas}} <- presences, into: %{} do
    {key, %{metas: metas, user: users[String.to_integer(key)]}}
  end
end

Account.get_users_map/1 可實作如下

def get_users_map(ids) do
  query =
    from u in User,
      where: u.id in ^ids,
      select: {u.id, u}

  query |> Repo.all() |> Enum.into(%{})
end

上述 fetch/2 函式會從已註冊提供給定主題的身分狀態資料庫中取得所有使用者。接著會將身分狀態資訊延伸到使用者的資訊身分狀態的 :user 金鑰，同時仍保留原始身分狀態資料中的必備 :metas 欄位。

將 Elixir 作為身分狀態用戶端使用

身分狀態非常適合外部用戶端使用，例如 JavaScript 應用程式，但它也能用於從 Elixir 用戶端處理作業，在伺服器發生時追蹤身分狀態變更。這可藉由實作身分狀態模組中的非必備 init/1 和 handle_metas/4 回呼來完成。例如，下列回呼會接收身分狀態資料變更，並廣播其他 Elixir 處理作業使用者加入和離開

defmodule MyApp.Presence do
  use Phoenix.Presence,
    otp_app: :my_app,
    pubsub_server: MyApp.PubSub

  def init(_opts) do
    {:ok, %{}} # user-land state
  end

  def handle_metas(topic, %{joins: joins, leaves: leaves}, presences, state) do
    # fetch existing presence information for the joined users and broadcast the
    # event to all subscribers
    for {user_id, presence} <- joins do
      user_data = %{user: presence.user, metas: Map.fetch!(presences, user_id)}
      msg = {MyApp.PresenceClient, {:join, user_data}}
      Phoenix.PubSub.local_broadcast(MyApp.PubSub, topic, msg)
    end

    # fetch existing presence information for the left users and broadcast the
    # event to all subscribers
    for {user_id, presence} <- leaves do
      metas =
        case Map.fetch(presences, user_id) do
          {:ok, presence_metas} -> presence_metas
          :error -> []
        end

      user_data = %{user: presence.user, metas: metas}
      msg = {MyApp.PresenceClient, {:leave, user_data}}
      Phoenix.PubSub.local_broadcast(MyApp.PubSub, topic, msg)
    end

    {:ok, state}
  end
end

handle_metas/4 回呼會接收主題、身分狀態差異、具有其身分資料的該主題的目前的狀態，以及從 init 和後續 handle_metas/4 呼叫累積的任何使用者端狀態。在我們的實作範例中，會在 diff 的 :joins 和 :leaves 中存取，並根據已知身分資料資訊填妥一個完整的狀態。然後會廣播給本機節點訂閱者關於使用者加入和離開。

身分狀態測試

每次呼叫 fetch 回呼，都會從個別處理作業中進行呼叫。由於這些處理作業會非同步執行，因此通常需要確保在每個測試結束時關閉它們。可透過使用 ExUnit 的 on_exit 鉤子加上 fetchers_pids 函式來達成

on_exit(fn ->
  for pid <- MyAppWeb.Presence.fetchers_pids() do
    ref = Process.monitor(pid)
    assert_receive {:DOWN, ^ref, _, _, _}, 1000
  end
end)