ShopifexWeb.AuthController behaviour (Shopifex v3.0.0)

Copy Markdown View Source

You can use this module inside of another controller to handle initial iFrame load and shop installation

Example:

defmodule MyAppWeb.AuthController do
  use MyAppWeb, :controller
  use ShopifexWeb.AuthController

  # Thats it! Validation, installation are now handled for you :)
end

Summary

Callbacks

An optional callback called after the installation is completed, the shop is persisted in the database and webhooks are registered. By default, this function redirects the user to the app within their Shopify admin panel.

An optional callback called after the oauth update is completed. By default, this function redirects the user to the app within their Shopify admin panel.

An optional callback which you can use to override how your app is rendered on initial load. If you are building a server-rendered app, you might just want to redirect to your index page. If you are building an externally hosted SPA, you probably want to redirect to the Shopify admin link for your app.

An optional callback which is called after the shop data has been retrieved from Shopify API. This function should persist the shop data and return a shop record.

Types

shop()

@type shop() :: %{access_token: String.t(), scope: String.t(), url: String.t()}

Callbacks

after_install(t, shop, oauth_state)

(optional)
@callback after_install(Plug.Conn.t(), shop(), oauth_state :: String.t()) :: Plug.Conn.t()

An optional callback called after the installation is completed, the shop is persisted in the database and webhooks are registered. By default, this function redirects the user to the app within their Shopify admin panel.

Example

@impl true
def after_install(conn, shop, oauth_state) do
  # send yourself an e-mail about shop installation

  # follow default behaviour.
  super(conn, shop, oauth_state)
end

after_update(t, shop, oauth_state)

(optional)
@callback after_update(Plug.Conn.t(), shop(), oauth_state :: String.t()) :: Plug.Conn.t()

An optional callback called after the oauth update is completed. By default, this function redirects the user to the app within their Shopify admin panel.

Example

@impl true
def after_update(conn, shop, oauth_state) do
  # do some work related to oauth_state

  # follow default behaviour.
  super(conn, shop, oauth_state)
end

auth(conn, params)

(optional)
@callback auth(conn :: Plug.Conn.t(), params :: Plug.Conn.params()) :: Plug.Conn.t()

An optional callback which you can use to override how your app is rendered on initial load. If you are building a server-rendered app, you might just want to redirect to your index page. If you are building an externally hosted SPA, you probably want to redirect to the Shopify admin link for your app.

Externally hosted SPA's will likely only hit this route on install.

The default implementation redirects to path_prefix <> "/". When the request carries an id_token (an App Bridge embedded load) it forwards only the embedded-context params (shop, host, embedded, locale, id_token) so the landing route can authenticate via the still-valid id_token. When id_token is absent — a legacy non-embedded app with no App Bridge — it forwards the complete original query Shopify signed (including hmac and timestamp) so the landing route's :shopify_session has something to re-verify instead of falling through to the store selector.

insert_shop(shop)

(optional)
@callback insert_shop(shop()) :: shop()

An optional callback which is called after the shop data has been retrieved from Shopify API. This function should persist the shop data and return a shop record.

Example

@impl true
def insert_shop(shop) do
  # make sure there is only one store in the database because we don't have
  # a unique index on the url column for some reason.

  case Shopifex.Shops.get_shop_by_url(shop.url) do
    nil -> super(shop)
    shop -> shop
  end
end