useSetOpenInAppUrl

Caution

Runtime Support: ChatGPT Apps only

This hook is not available in MCP Apps. Calling it in an MCP Apps environment will throw an error.

The useSetOpenInAppUrl hook returns a function to set the URL that will be opened when the user clicks the “open in app” button. This button appears in the top right corner when the view is displayed in fullscreen mode.

Basic usage

import { useSetOpenInAppUrl } from "@usefractal/frac/web";

function SetAppUrl() {
  const setOpenInAppUrl = useSetOpenInAppUrl();

  const handleSetUrl = async () => {
    try {
      await setOpenInAppUrl("https://example.com/app");
    } catch (error) {
      console.error("Failed to set URL:", error);
    }
  };

  return (
    <button onClick={handleSetUrl}>
      Set App URL
    </button>
  );
}

Returns

setOpenInAppUrl: (href: string) => Promise<void>

An async function that sets the URL to be opened when the user clicks the “open in app” button. The function returns a Promise that resolves when the URL has been successfully set.

Parameters

• href: string
  • Required
  • The URL to set.
  • If the origin matches the view’s server URL, ChatGPT navigates to the full href.
  • If the origin differs from the view’s server URL, ChatGPT ignores the href and falls back to the view’s server URL.

Errors

The function may throw errors in the following cases:

• If href is empty or only whitespace: "The href parameter is required."

Examples

Setting URL with Form Input

import { useSetOpenInAppUrl } from "@usefractal/frac/web";
import { useState } from "react";

function UrlSetter() {
  const setOpenInAppUrl = useSetOpenInAppUrl();
  const [url, setUrl] = useState("");
  const [error, setError] = useState<string | null>(null);
  const [success, setSuccess] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError(null);
    setSuccess(false);

    try {
      await setOpenInAppUrl(url);
      setSuccess(true);
    } catch (err) {
      setError(err instanceof Error ? err.message : "Failed to set URL");
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={url}
        onChange={(e) => setUrl(e.target.value)}
        placeholder="Enter URL"
      />
      <button type="submit">Set URL</button>
      {success && <p>✓ URL successfully set!</p>}
      {error && <p>× {error}</p>}
    </form>
  );
}

Dynamic URL Based on State

import { useSetOpenInAppUrl, useDisplayMode } from "@usefractal/frac/web";
import { useEffect } from "react";

function ProductDetail({ productId }: { productId: string }) {
  const setOpenInAppUrl = useSetOpenInAppUrl();
  const [displayMode] = useDisplayMode();

  useEffect(() => {
    if (displayMode === "fullscreen") {
      const productUrl = `https://example.com/products/${productId}`;
      setOpenInAppUrl(productUrl).catch(console.error);
    }
  }, [displayMode, productId, setOpenInAppUrl]);

  return (
    <div>
      <h2>Product {productId}</h2>
      {/* Product details */}
    </div>
  );
}