Note

Journeys is becoming Banners. Opt-in access starts October 13, 2026. To get access, fill out the Banners opt-in form. Your existing Journeys keep running whether or not you opt in.

Branch Banners uses the Branch Web SDK to show banners on your website and Branch Links to open your app. This guide covers the setup your marketing team needs before launch, the Web SDK calls that control banners, and fixes for common problems.

To learn how marketers build banner campaigns, see the Banners Overview.

Set up Banners

Complete these steps before your marketing team previews its first banner. Previews run on your own web pages, so they need this setup too.

Add the Web SDK to your website

Add and initialize the Branch Web SDK on every page where a banner can appear. Pages without it never show a banner. See Web SDK Basic Integration.

If your site doesn't use a mobile viewport tag, mobile banners render too small. Add this tag inside the page's <head> element:

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Integrate the app SDKs

Integrate the Branch iOS SDK and Branch Android SDK into your apps. The app SDKs pass the banner's link data to your app, which uses it to route visitors to content. They also report installs and in-app events to Branch. Without them, banners still show and send visitors to your app, but Branch can't deep link them to content or credit installs and events to the banner.

See iOS Basic Integration and Android Basic Integration.

Add the alternate domain

The links in your banners use your -alternate.app.link domain to open your app through iOS Universal Links and Android App Links. Add the domain alongside your other Branch domains:

• On iOS, add applinks:<subdomain>-alternate.app.link to your Associated Domains. See Configure associated domains.
• On Android, add an intent filter for the <subdomain>-alternate.app.link domain. See Configure app.

To find your alternate domain, see Link domain. If you use a custom link domain, you still need the -alternate.app.link domain.

Add Branch to your security policy

If your site uses a Content Security Policy (CSP), add the Branch domains the Web SDK uses. These include cdn.branch.io, api2.branch.io, and your link domain. For examples, see Implement Content Security Policy (CSP).

If your policy uses nonces for inline scripts, pass the page's nonce in the nonce option when you initialize the SDK. The Web SDK adds it to the branch-journey-cta script it injects, which lets that script run under your policy.

branch.init('<branch_key>', { nonce: '<your_nonce>' });

Test the setup

To test, you need a campaign with a creative selected. Ask your marketing team for a draft, or create one. See Create a Banner Campaign.

1. In the campaign builder, select Preview Link.
2. In Webpage URL, enter a page that runs the Web SDK.
3. Select Generate Banner Preview Link.
4. Scan the QR code, or open the link on the device type the campaign targets.

If the banner appears, the Web SDK works on that page. If it doesn't, see Troubleshoot banners.

Control banners with the Web SDK

The Web SDK options, methods, and events that control banners have "journey" in their names. For full signatures, see the Web SDK Full Reference.

Hide banners on a page

To keep banners off a page, such as a checkout page, pass the no_journeys option when you initialize the SDK:

branch.init('<branch_key>', { no_journeys: true });

Close a banner

To close a banner from your code, such as after a timeout or a user action, call the closeJourney method:

branch.closeJourney(function(err) {
  // The err argument is set if closing fails
});

Show a banner again

To show a banner again after you hide banners with no_journeys or close one with closeJourney, log a page view:

branch.track('pageview');

A page view doesn't override a visitor's dismissal. A banner the visitor dismissed stays hidden for its dismissal period.

Turn off animations

To show and hide banners without their entry and exit animations, pass these options when you initialize the SDK:

branch.init('<branch_key>', {
  disable_entry_animation: true,
  disable_exit_animation: true
});

You can also pass them to branch.track as its third argument.

Set link data from the page

To pass page-specific link data to the banner's call to action (CTA), call setBranchViewData after you initialize the SDK. Your app receives the values when the visitor opens it from the banner.

branch.setBranchViewData({
  data: {
    '$deeplink_path': 'product/1234',
    'product_id': '1234'
  }
});

Campaigns can also set link data in Link Data Configuration. Set each key in one place only. For the keys Branch recognizes, see Link data.

Set page metadata for targeting

Marketers can target pages with the Is viewing a page with metadata key audience attribute. To provide that metadata, pass string key-value pairs in the metadata option when you initialize the SDK:

branch.init('<branch_key>', {
  metadata: { category: 'shoes' }
});

You can also add metadata with Branch meta tags in the page's HTML, or pass it as the second argument of a branch.track('pageview') call. For the tag format, see Include deep link data in HTML.

Listen for banner events

Register a listener to react to the banner lifecycle:

branch.addListener('didShowJourney', function(event, data) {
  // The banner is visible
});

You can listen for these events:

Event	When it fires
willShowJourney	A banner is about to show
didShowJourney	The banner's entry animation finished and it's visible
willNotShowJourney	No banner will show on this page view
didClickJourneyCTA	The visitor selected the CTA
didClickJourneyClose	The visitor selected the close button
didClickJourneyContinue	The visitor selected the dismiss text
willCloseJourney	The banner's exit animation started
didCloseJourney	The banner's exit animation finished and it's no longer visible
didCallJourneyClose	Your code called the closeJourney method

To listen for every event, call branch.addListener with only the listener function.

Credit referring links

A visitor can reach your site from a Branch Link, such as one in an ad or email, and then select a banner in the same session. Branch credits the resulting install or open to that referring link by default. If the referring link deep links into your app, that deep link carries through too.

To credit the banner instead, set make_new_link to true when you initialize the SDK:

branch.init('<branch_key>', { make_new_link: true });

To keep crediting the referring link when the visitor comes back in a later session, turn on the enableExtendedJourneysAssist option. The extendedJourneysAssistExpiryTime option sets how long that lasts, in milliseconds. The default is seven days.

branch.init('<branch_key>', {
  enableExtendedJourneysAssist: true,
  extendedJourneysAssistExpiryTime: 1209600000 // 14 days
});

Banner HTML

Each banner renders inside the #branch-banner-iframe iframe on your page. Within it, the #branch-banner element wraps the banner and the .branch-banner-content element holds its contents.

The code editor shows this HTML for legacy creatives, and it won't save until the elements every banner needs are present. For the full list, see Edit legacy creatives.

Troubleshoot banners

Use these checks when a banner doesn't show, doesn't open the app, or shows the wrong text.

The banner doesn't appear

Check the page first, then the campaign, then your test browser:

1. Look for a request to api2.branch.io in your browser's network tools. A request means the Web SDK runs on the page.
2. Check the browser console for errors if there's no request. Ad blockers, browser tracking protections, and a CSP that blocks the Branch domains can stop the Web SDK from loading.
3. Check that the page doesn't pass the no_journeys option.
4. Check that the campaign is Active and that the current time falls inside its schedule.
5. Compare the page URL with the campaign's placement rules.
6. Compare the device and visitor with the campaign's audience rules.
7. Check whether a campaign with a higher priority also matches. Branch shows only the highest-priority match. See Set priority.
8. Test in a private window, because a banner you dismissed stays hidden for its dismissal period. On iOS, use a browser other than Safari. Safari's Advanced Tracking and Fingerprinting Protection can block the Web SDK in private browsing.

The CTA doesn't open the app

Confirm that your -alternate.app.link domain is in your iOS Associated Domains and Android intent filters. Also check that your apps initialize the Branch iOS SDK and Branch Android SDK. See Add the alternate domain.

The CTA still shows the no-app text

Branch knows a visitor has your app only after the app opens from a Branch Link. Until then, the visitor sees the Text (no app) version of the CTA, even right after they install. On a test device, go back to the page and select the CTA again to open the app. The CTA text can take several minutes to change.

"Has the app installed" doesn't work in testing

The Has the app installed attribute works only when your website and app use the same Branch key. Test with your live key in both, because test mode doesn't store the device data that app detection relies on.

Find the link behind a banner

To check the link and link data behind a live banner, inspect the page's network traffic.

1. Open your browser's developer tools.
2. Switch to mobile view.
3. Load the page with the banner.
4. In the Network tab, enter branch in the filter.
5. Select the pageview request.
6. In the response, search for app.link to find the banner's link.
7. Open the link with ?debug=1 at the end to see its data.