Embedded Settings

Embedded settings allows you to provide a settings page for users of your app. This will be available when clicking through the app tile on the apps page.

You can see an example with the Twitch Merch Train app.

This works similarly to embedded sections.

Getting started

You will specify the URL of the iframe that will be rendered on your app page, under Settings URL.

Signature

Like embedded sections, this will be called with an HMAC signature.

Here are the parameters that will be passed to the iframe:

• timestamp: The timestamp of when the signature was generated.
• shop_id: The shop id of the creator using your app.
• hmac: The HMAC signature.

The signature is generated using the following data string:

timestamp=${timestamp}&shop_id=${id}&app_id={app_id}

To verify the signature, you will recalculate the HMAC signature using the parameters above and your secret key.

The HMAC here is in base64 vs. hex in the embedded sections.

Your HMAC secret key is available in the basic information section of your Platform App settings

async function getHmacKey(secret: string): Promise<CryptoKey> {
  const encoder = new TextEncoder();
  const keyData = encoder.encode(secret);
  return await crypto.subtle.importKey(
    'raw',
    keyData,
    { name: 'HMAC', hash: 'SHA-512' },
    false,
    ['sign', 'verify']
  );
}

export async function verifySignature(params: {
  shopId: string,
  appId: string,
  timestamp: string,
}, hmacSignature: string, secret: string): Promise<boolean> {
  const { shopId, appId, timestamp } = params;

  const encoder = new TextEncoder();
  const key = await getHmacKey(secret);

  // Construct the data string from the individual fields
  const data = `timestamp=${timestamp}&shop_id=${shopId}&app_id=${appId}`;

  // Generate the HMAC for the constructed data
  const messageData = encoder.encode(data);
  const signature = await crypto.subtle.sign(
    'HMAC',
    key,
    messageData
  );

  // Convert the provided header to the same format
  const providedSignature = base64ToUint8Array(hmacSignature);  

  // Compare the signatures
  if (signature.byteLength !== providedSignature.length) {
    return false;
  }
  
  return crypto.subtle.verify('HMAC', key, providedSignature, messageData);    
}