Use with Shopify App Bridge

Apps that use Hydrogen, Remix, or Shopify App Bridge will likely need to perform external redirects. When building with Mantle, some actions such as subscribing to a plan, require redirecting the user's browser to a different URL. This external redirect is needed because embedded Shopify apps are securely iframe'd and can't change the parent page's url. The standard method that Shopify App Bridge provides is to use the Redirect action.

Common scenarios

You'll need App Bridge redirects for several Mantle operations:

• Plan subscription confirmations
• Usage limit increase approvals
• OAuth authentication flows
• Returning from Shopify confirmation screens

Implementation

Here's how to handle redirects properly in a React component:

import { Redirect } from "@shopify/app-bridge/actions";
import { useContext } from "react";
import { Context as ShopifyContext } from "@shopify/app-bridge-react";
import { Button } from "@shopify/polaris";
import { useMantle } from "@heymantle/react";

// Inside your component function
function PlansPage() {
  // Get the App Bridge context
  const app = useContext(ShopifyContext);
  const { plans, client } = useMantle();
  
  // This function handles the subscription and redirect
  const handleSubscribe = async (planId) => {
    try {
      // 1. Create the subscription
      const subscription = await client.subscribe({
        planId: planId,
        returnUrl: '/plans'
      });
      
      // 2. Check for errors
      if (subscription.error) {
        console.error('Unable to subscribe:', subscription.error);
        return;
      }
      
      // 3. Get the confirmation URL
      const confirmationUrl = subscription.confirmationUrl;
      
      // 4. Create and dispatch the redirect
      const redirect = Redirect.create(app);
      redirect.dispatch(Redirect.Action.REMOTE, confirmationUrl);
    } catch (error) {
      console.error('Subscription error:', error);
    }
  };
  
  return (
    <div>
      <h1>Available Plans</h1>
      {plans.map(plan => (
        <div key={plan.id}>
          <h2>{plan.name}</h2>
          <p>${plan.amount}/month</p>
          <Button onClick={() => handleSubscribe(plan.id)}>
            Subscribe
          </Button>
        </div>
      ))}
    </div>
  );
}

Security considerations

The iframe security model is important for several reasons:

• Prevents unauthorized access to the Shopify admin
• Ensures proper session handling
• Maintains consistent user experience
• Protects merchant data

Always use App Bridge's Redirect action rather than direct window.location changes to maintain these security benefits.

Common issues and solutions

1. Redirect not working

   • Verify App Bridge is properly initialized
   • Check that the URL is properly encoded
   • Ensure you're using REMOTE action for external URLs

2. Session issues after redirect

   • Always include return_url in subscription calls
   • Handle session rehydration after return
   • Use proper scoping for App Bridge context

3. Mobile considerations

   • Test redirects on mobile devices
   • Account for different screen sizes
   • Handle mobile-specific authentication flows

Our example app has a more complete example showing how all of this comes together in a production context.