# Embedded Apps

Apps registered as embedded open in a frame (iframe) on the app page of the store admin panel. In this case the panel does not go through the authorization URL; it opens your Redirect URL directly with signed parameters, and your app starts its own authorization request if needed after verifying the store.

<Steps>
  <Step from="merchant" to="panel" title="Opens the app detail on the Apps page" />
  <Step from="panel" to="app" title="Opens your app in a frame">
    Your Redirect URL with `embedded`, `domain`, `date`, `renew_date` when present, and `hmac`.
  </Step>
  <Step from="app" title="Verifies hmac and date">
    Reject the URL if `date` is not today or yesterday.
  </Step>
  <Step from="app" to="panel" title="Requests authorization if there is no session">
    `/panel/auth` with a `state` you generate.
  </Step>
  <Step from="panel" to="app" title="Returns with a code">
    No consent screen is shown because the app is already installed.
  </Step>
  <Step from="app" to="api" title="Exchanges the code for tokens">
    `POST /oauth/v2/token`
  </Step>
  <Step from="app" to="merchant" title="Shows its UI inside the panel" />
</Steps>

## Opening URL

```http
GET https://your-app.example.com/ideasoft/callback
    ?embedded=1
    &domain=your-store.myideasoft.com
    &date=20260518
    &renew_date=20270401
    &hmac=911c99c9e9da28f884db4fb5c514a9a9861bc9b8558cc3ab7d10f06304a9b393
```

| Parameter | Description |
|---|---|
| `embedded` | Always `1`. |
| `domain` | The store's domain **without the scheme** (e.g. `your-store.myideasoft.com`). |
| `date` | The day the URL was produced, `YYYYMMDD` (Turkey time). |
| `renew_date` | Annually renewed products only: renewal date, `YYYYMMDD`. |
| `hmac` | HMAC-SHA256 signature of the parameters above. |

:::warning{title="The Redirect URL must not contain a query string"}
The panel appends these parameters to your Redirect URL with `?`. If your registered URL already contains `?`, the opening URL breaks.
:::

## Verifying hmac

```
hmac = hex( HMAC-SHA256( JSON, client_secret ) )

JSON (without renew_date):
{"embedded":"1","domain":"<domain>","date":"<date>"}

JSON (with renew_date):
{"embedded":"1","domain":"<domain>","date":"<date>","renew_date":"<renew_date>"}
```

- As with [state verification](/app-store/installation#verifying-state), the text is PHP `json_encode` output: fixed key order, no whitespace.
- `embedded` is the string `"1"`, not a number.
- `date` is sent in the URL; compute the signature with that value, then check that the date is **today or yesterday**. Reject older URLs.
- Compare in constant time.

<CodeTabs>

```php title="PHP"
<?php
function verifyEmbedded(array $query, string $clientSecret): bool
{
    $data = [
        'embedded' => (string)($query['embedded'] ?? ''),
        'domain' => $query['domain'] ?? '',
        'date' => $query['date'] ?? '',
    ];
    if (!empty($query['renew_date'])) {
        $data['renew_date'] = $query['renew_date'];
    }
    $expected = hash_hmac('sha256', json_encode($data), $clientSecret);
    if (!hash_equals($expected, (string)($query['hmac'] ?? ''))) {
        return false;
    }

    $today = new DateTimeImmutable('now', new DateTimeZone('Europe/Istanbul'));
    $allowed = [$today->format('Ymd'), $today->modify('-1 day')->format('Ymd')];
    return in_array($data['date'], $allowed, true);
}
```

```js title="Node.js"
// ideasoftHmac, safeEqual and ymd helpers: same as in the Installation and Authorization example
export function verifyEmbedded(query, clientSecret) {
  const data = {
    embedded: String(query.embedded ?? ""),
    domain: query.domain ?? "",
    date: query.date ?? "",
  };
  if (query.renew_date) data.renew_date = query.renew_date;
  const expected = ideasoftHmac(data, clientSecret);
  if (!safeEqual(expected, query.hmac ?? "")) return false;

  const now = Date.now();
  return [ymd(new Date(now)), ymd(new Date(now - 86_400_000))].includes(data.date);
}
```

```python title="Python"
# ideasoft_hmac helper: same as in the Installation and Authorization example
def verify_embedded(query, client_secret):
    data = {
        "embedded": str(query.get("embedded", "")),
        "domain": query.get("domain", ""),
        "date": query.get("date", ""),
    }
    if query.get("renew_date"):
        data["renew_date"] = query["renew_date"]
    expected = ideasoft_hmac(data, client_secret)
    if not hmac.compare_digest(expected, query.get("hmac", "")):
        return False

    now = datetime.now(ZoneInfo("Europe/Istanbul"))
    return data["date"] in (now.strftime("%Y%m%d"), (now - timedelta(days=1)).strftime("%Y%m%d"))
```

</CodeTabs>

**Test vector:** for `client_secret=example-client-secret`, `domain=your-store.myideasoft.com` and `date=20260518` (no `renew_date`) the signed text is `{"embedded":"1","domain":"your-store.myideasoft.com","date":"20260518"}` and `hmac` is `911c99c9e9da28f884db4fb5c514a9a9861bc9b8558cc3ab7d10f06304a9b393`.

:::caution{title="hmac is not a session"}
`hmac` only signs the store and the day, so it can be reused within the same day. Do not treat it as a persistent session or as API authorization, and do not write it to logs. Complete the authorization below to access store data.
:::

## Authorization

If you have no valid session or tokens for this store, redirect from within the frame to the store's authorization URL with a `state` value you generate:

```http
GET https://your-store.myideasoft.com/panel/auth
    ?client_id=<client_id>
    &response_type=code
    &redirect_uri=<registered redirect_uri>
    &state=<random value you generate>
```

Because the app is already installed on the store, no consent screen is shown; the store returns to your Redirect URL with `state`, `code`, `domain` and `user_id`. In this flow `state` is **the value you sent**, not an Ideasoft signature; compare it with the value you stored. Then [exchange the code for tokens](/app-store/installation#obtaining-tokens).

## Running inside a frame

- Your app opens in a frame inside the store admin panel. Frame-blocking headers (`X-Frame-Options`, `Content-Security-Policy` with `frame-ancestors`) must allow store domains to display your app.
- Browsers may restrict third-party cookies inside frames. Do not tie your session to cookies alone; design it so it can be re-established on every opening through `hmac` verification and the authorization flow.
