Диплинки и динамические ссылки

Диплинк — ссылка, которая открывает конкретный экран приложения, а не главную. Вместе со ссылкой можно передать данные, по которым экран поймёт, что именно показывать.

Пример: вы отправили другу пост из соцсети, и он открывается сразу — искать его в приложении руками не нужно, всё работает как обычная ссылка на сайт.

Схема работы:

При переходе по ссылке сначала проверяется, установлено ли приложение. Если нет — открывается App Store или Google Play. После установки, если экран закрыт авторизацией, покажется вход, а уже потом — то, чем с вами поделились.

Важная особенность: обычный путь к экрану внутри приложения может быть длинным — «Главная → Все посты → Пост». Ссылка его пропускает и ведёт сразу на нужную страницу.

Диплинк

Диплинк открывает конкретный экран приложения — при условии, что приложение уже установлено на устройстве.

Структура ссылки

Ссылка состоит из трёх частей: схема, хост и имя страницы — например, designersapp://designersapp.com/profile.

Без имени страницы (designersapp://mydesignersapp.com/) откроется стартовый экран.

Настройка

Разберём на примере: делимся ссылкой на страницу профиля и открываем её.

Четыре шага:

1. Задать схему URL
2. Задать адрес страницы
3. Настроить отправку ссылки
4. Проверить ссылку

1. Схема URL

1. Откройте Settings & Integrations > General > App Details.

2. Если диплинки ведут на несколько страниц и все они требуют входа, включите Pages Requires Authentication by Default.

3. В полях URL scheme уже стоят значения, собранные из имени проекта. Поменяйте scheme (до ://) и hostname (после ://), если нужно своё.

4. Переключатель Pages Are Subroutes of Root Page делает так, что кнопка «назад» с открытой по ссылке страницы ведёт на главную, а не закрывает приложение.

2. Адрес страницы

Адрес страницы используется и в вебе, и для диплинков на мобильных.

1. Выберите страницу, которая должна открываться по ссылке.

2. В панели свойств справа откройте раздел Route Settings.

3. По умолчанию маршрут совпадает с именем страницы — измените, если в адресе нужно другое.

4. Отметьте Requires Authentication, если страница доступна только после входа.

3. Отправка ссылки

Отправить диплинк текущей страницы можно действием Share.

1. Откройте страницу, ссылку на которую нужно отдавать.

2. Выделите виджет — например, кнопку «Поделиться».

3. Выберите Actions в панели свойств и нажмите Open — откроется Action Flow Editor.

   1. Нажмите + Add Action.
   2. Справа найдите действие Share.
   3. Value Source — From Variable.
   4. Source — Global Properties.
   5. Available Options — Link To Current Page, затем Close.

4. Проверка

В Run Mode диплинки не работают — проверять нужно на устройстве или эмуляторе.

Сначала получите саму ссылку: запустите приложение на устройстве, нажмите кнопку «Поделиться» и скопируйте её.

Дальше есть два способа.

adb shell am start -a android.intent.action.VIEW \
    -c android.intent.category.BROWSABLE \
    -d "designersapp://designersapp.com/profile"

Firebase Dynamic Links (не поддерживается)

Динамическая ссылка тоже открывает конкретный экран, но, в отличие от диплинка, переживает установку приложения: если приложения нет, пользователь попадает в магазин, а после установки — сразу на нужную страницу.

Работает она поверх диплинка — то есть его нужно настроить в любом случае.

Шаги были такие:

1. Настроить домен
2. Настроить iOS
3. Задать схему URL
4. Задать адрес страницы
5. Настроить отправку ссылки
6. Проверить ссылку

1. Домен

Динамической ссылке нужен домен — он становится префиксом адреса.

1. Откройте консоль Firebase и выберите Dynamic Link в меню слева.

2. Нажмите Get Started.

3. Введите домен. Своего нет — возьмите бесплатный Google Provided Domain, оканчивающийся на page.link. Для своего домена см. инструкцию Firebase.

4. С доменом от Google на этом можно закончить — Finish.

2. Настройка iOS

Для работы на iOS требовались два дополнительных шага.

2.1 App Store ID и Team ID в проекте Firebase

1. Откройте консоль Firebase и выберите Project Overview.

2. Выберите проект iOS и нажмите значок шестерёнки.

3. Прокрутите до выбранного проекта iOS.

4. В поле App Store ID нажмите на карандаш, введите идентификатор и нажмите Save. Где его взять, подсказывает значок вопроса рядом.

5. То же самое для поля Team ID.

2.2 Возможность Associated Domains

1. Откройте портал разработчика Apple и выберите Certificates, IDs & Profiles.

2. Выберите Identifiers и нажмите на идентификатор своего приложения.

3. Отметьте Associated Domains и нажмите Save.

3. Схема URL

1. Откройте Settings & Integrations > General > App Details.

2. Если ссылки ведут на страницы, требующие входа, включите Pages Requires Authentication by Default.

3. Включите Use Firebase Dynamic Links.

4. В полях URL scheme задайте scheme (до ://) и hostname (после ://).

5. Включите Pages Are Subroutes of Root Page, чтобы кнопка «назад» вела на главную, а не закрывала приложение.

4. Адрес страницы

1. Выберите страницу, которая должна открываться по ссылке.

2. В панели свойств откройте раздел Route Settings.

3. При необходимости измените маршрут — по умолчанию он совпадает с именем страницы.

4. Отметьте Requires Authentication, если страница доступна только после входа.

5. Отправка ссылки

Здесь нужны два действия подряд: Generate Current Page Link собирает ссылку, Share её отправляет.

1. Откройте нужную страницу.

2. Выделите виджет — например, кнопку «Поделиться».

3. Добавьте действие Generate Current Page Link.

4. Нажмите + под его блоком и выберите Add Action.

5. Справа найдите действие Share.

6. Value Source — From Variable.

7. Source — Widget State.

8. Available Options — Current Page Link, затем Close.

6. Проверка

В Run Mode динамические ссылки не работают — нужно устройство или эмулятор.

Запустите приложение, нажмите «Поделиться» и скопируйте ссылку. Затем вставьте её в адресную строку мобильного Firefox.

Передача данных в ссылке

Обычно вместе со ссылкой нужно передать данные: код скидки для страницы товара, идентификатор профиля для страницы профиля. По ним страница и понимает, что показывать.

Нужно две вещи.

1. Параметр на целевой странице.

2. Этот же параметр в маршруте, в Route Settings, с двоеточием перед именем — например, profilePage/:profileId.

Этого достаточно и для диплинка, и для динамической ссылки.

Диплинки через Branch.io

Раз Firebase Dynamic Links больше нет, для новых проектов берут Branch.io — кроссплатформенный сервис диплинков, в том числе отложенных (тех, что срабатывают после установки приложения).

Свой бэкенд для этого писать не нужно.

Настройка в Branch.io

Заведите проект в панели Branch и дальше по шагам.

1. Branch Key

Первым делом запишите Branch Key — он понадобится при настройке FlutterFlow.

Этот ключ однозначно определяет ваше приложение.

2. Ссылки перенаправления

В панели Branch задаются запасные адреса — куда отправить пользователя, если приложение не установлено. Обычно это App Store, Google Play или страница на сайте.

Без них ссылка ведёт в никуда у всех, кто ещё не поставил приложение, — то есть у большей части получателей.

3. Smart Link

Дальше на вкладке Quick Links создаётся сама ссылка: заголовок, псевдоним, метки для аналитики и превью для соцсетей — картинка, заголовок, описание.

После сохранения Branch выдаст готовую Smart Link.

Настройка проекта FlutterFlow

Чтобы Smart Links заработали, нужно поправить нативные конфигурационные файлы на вкладке Custom Code.

1. Заведите переменные окружения:

   • branchHostUrl — например, brnch4.app.link;
   • branchKey — рабочий ключ Branch. Для отладки можно завести отдельный branchKeyTest и переключаться между окружениями и в панели Branch, и во FlutterFlow.

2. Откройте FlutterFlow > Custom Code.

Android

1. В AndroidManifest.xml создайте переменные branchKey и branchHostUrl и привяжите их к переменным окружения.

2. Через хук Activity Tags добавьте в Main Activity блок intent-filter:

<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:scheme="https" android:host="{{branchHostUrl}}"/>
</intent-filter>

3. В блок App Component добавьте метаданные:

<meta-data android:name="io.branch.sdk.BranchKey" android:value="{{branchKey}}"/>
<meta-data android:name="io.branch.sdk.TestMode" android:value="false"/>

iOS

1. В Info.plist создайте переменную branchKey и привяжите её к переменной окружения.

2. Туда же добавьте:

<key>branch_key</key>
<string>{{branchKey}}</string>

3. В Runner.entitlements создайте переменную branchHostUrl и привяжите её к переменной окружения.

4. Туда же добавьте:

<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:{{branchHostUrl}}</string>
</array>

Файл apple-app-site-association, нужный для Universal Links, Branch хостит сам — вручную выкладывать его на домен не надо.

Маршрутизация во FlutterFlow

FlutterFlow по умолчанию заводит собственную URI-схему вида myapp://. Даже если ссылки у вас на https://, эту схему стоит держать согласованной с настройками Branch.

1. Откройте Settings & Integrations > App Settings > App Details.

2. Прокрутите до раздела Routing & Deep Linking.

3. В Custom URI Scheme укажите тот же хост, что задан в панели Branch, — например, brnch4:// или dreambrush://.

Внутренняя маршрутизация FlutterFlow опирается на эту схему, поэтому расхождение приводит к переходам не на те экраны.

Подключение Flutter Branch SDK

За связь с Branch отвечает пакет flutter_branch_sdk.

1. Откройте Settings and Integrations > Pubspec Dependencies и добавьте зависимость:

flutter_branch_sdk: ^5.0.1

Актуальную версию смотрите на pub.dev.

2. Создайте собственное действие, инициализирующее SDK при запуске приложения:

import 'package:flutter_branch_sdk/flutter_branch_sdk.dart';

Future initBranch() async {
  // Add your function code here!
  await FlutterBranchSdk.init();
}

Вызовите его в Final Actions файла main.dart.

3. Создайте второе действие — слушатель переходов по ссылкам:

// Automatic FlutterFlow imports
import '/flutter_flow/flutter_flow_theme.dart';
import '/flutter_flow/flutter_flow_util.dart';
import '/custom_code/actions/index.dart'; // Imports other custom actions
import '/flutter_flow/custom_functions.dart'; // Imports custom functions
import 'package:flutter/material.dart';
// Begin custom action code
// DO NOT REMOVE OR MODIFY THE CODE ABOVE!

import 'dart:async';
import 'package:flutter_branch_sdk/flutter_branch_sdk.dart';
import 'package:flutter/services.dart';

StreamSubscription<Map>? _branchSubscription; // подписка на события Branch
final Set<String> _handledBranchLinks = {};

Future handleBranchDeeplink(Future Function(dynamic data) onLinkOpened) async {
   // Add your function code here!

   if (_branchSubscription != null) return; // уже слушаем — второй раз не подписываемся

   _branchSubscription = FlutterBranchSdk.listSession().listen(
           (data) async {
      final clicked = data['+clicked_branch_link'] == true;
      if (!clicked) return;

      final uniqueId = data['~referring_link'] ?? data['deeplink_path'] ?? '';

      if (_handledBranchLinks.contains(uniqueId)) return;
      _handledBranchLinks.add(uniqueId);

      await onLinkOpened(Map<String, dynamic>.from(data)); // вызываем действие пользователя с данными ссылки
   },
   onError: (error) {
      if (error is PlatformException) {
         print('[Branch] PlatformException: ${error.code} - ${error.message}');
      } else {
         print('[Branch] Unknown error: $error');
      }
   },
);
}

При создании ссылки в неё можно положить произвольные пары ключ-значение — "page": "paywall", "navigation_type": "bottom_sheet" — и здесь по ним решать, куда вести пользователя.

Проверять нужно оба сценария: переход при уже установленном приложении и переход с установкой (отложенный диплинк).

Инициализация SDK

Откройте main.dart и добавьте собственное действие initBranch в раздел Final Actions — так SDK инициализируется при запуске приложения.

Действие Handle Branch Deeplink

Действие handleBranchDeeplink слушает входящие ссылки и решает, куда вести пользователя. Его добавляют на входную страницу или на страницу после входа, на триггер onPageLoad, и обязательно первым в потоке действий.

Обратный вызов onLinkOpened

Когда ссылка получена, срабатывает onLinkOpened с данными ссылки — в нём и пишется логика перехода.

Параметр linkData

linkData — это Map со всеми метаданными, которые пришли со ссылкой.

Вот что приходит в приложении Dreambrush:

{
   "$og_title": "Check out my Ai Image on DreamBrush!",
   "$publicly_indexable": true,
   "imageId": "QiC94EaGNoonEKzln07A",
   "~creation_source": 4,
   "$og_description": "This image was created with DreamBrush app. You can check it out here.",
   "+click_timestamp": 1750099254,
   "$match_duration": 100000,
   "~feature": "Ai Image Creation",
   "$tags[0]": "generation",
   "+match_guaranteed": true,
   "$alias": "",
   "$canonical_identifier": "/imageDetails/QiC94EaGNoonEKzln07A",
   "+clicked_branch_link": true,
   "~id": "1461141612502859827",
   "+is_first_session": false,
   "~campaign": "Image Generation",
   "~referring_link": "https://dreambrush.app.link/DZ9liDTc6Tb",
   "~channel": "Share"
}

Ключи, которые важны на практике:

• $canonical_identifier — маршрут, заданный при создании ссылки (например, /imageDetails/:id). Задаётся действием Generate Link; если не задать, Branch выведет его сам из содержимого ссылки.

• ~referring_link — полный адрес ссылки, по которой перешли.

• $og_title — заголовок в превью ссылки, задаётся действием Generate Link.

• $og_description — описание под заголовком в превью, задаётся там же.

• ~channel, ~feature, ~campaign и $tags[0] — метки аналитики Branch. Задаются при создании ссылки и нужны, чтобы разбирать статистику переходов по каналам и кампаниям.

• page — не служебный ключ Branch, а общепринятое соглашение: имя экрана, который нужно открыть (paywall, productPage, onboardingStep2).

• Любые другие пары, добавленные при создании ссылки, — productId, referrer и так далее. И ключ, и значение должны быть строками.

По этим данным строится ветвление: например, показать нижнюю панель вместо перехода на страницу.

Что обычно делают в обработчике:

• переходят на страницу;
• открывают нижнюю панель;
• подгружают содержимое из Firestore по идентификатору из ссылки.

Навигация через глобальный контекст

Если главная страница рано убирается из стека навигации, обычный переход по локальному контексту перестаёт работать. Лечится это подменой локального контекста на глобальный контекст навигатора — тогда переход не зависит от того, что сейчас в дереве виджетов.

Разбор — в примере с DreamBrush.

Действие Generate Link

Действие generateLink создаёт Smart Link прямо из приложения. Это нужно, когда пользователь:

• делится содержимым — постом, товаром, картинкой;
• приглашает других по реферальному коду;
• отправляет ссылку, ведущую на конкретный экран.

Параметры действия:

• canonicalIdentifier — уникальный путь к содержимому (например, /imageDetails/:id). По нему пользователь и возвращается в приложение.

• title — заголовок ссылки, он же в превью и в аналитике.

• description — короткое описание, необязательно.

• metadata — произвольные пары, которые уйдут вместе со ссылкой: page: "imageDetails", imageRef: "abc123" и так далее.

• linkProperties — настройки поведения ссылки: feature, channel, campaign, stage.

Вспомогательные функции

Эти функции достают значения из данных ссылки и помогают ветвить навигацию.

• isTargetingPage(linkData, targetPage) — проверяет, совпадает ли значение page из ссылки с именем экрана. Само значение задаётся при создании ссылки — в панели Branch или во FlutterFlow.

• getCanonicalIdentifierFromLink(linkData) — возвращает маршрут, привязанный к ссылке (например, /imageDetails/abc123).

• getReferringLinkFromLink(linkData) — возвращает полный адрес ссылки из ключа ~referring_link. Нужен для аналитики и проверки источника перехода.

• getLastPathSegmentFromMap(linkData, key) — вытаскивает последний сегмент пути: из /imageDetails/abc123 вернёт abc123.

• getLinkValue(linkData, key) — безопасно достаёт любое значение по ключу; если ключа нет, вернёт null.

• createLinkProperties(...) — собирает Map настроек для создания ссылки: feature, campaign, stage, channel, псевдоним, метки, свои запасные адреса.

Пример: DreamBrush

В приложении DreamBrush generateLink вызывается после того, как пользователь сгенерировал изображение. В ссылку кладутся:

• canonicalIdentifier — маршрут текущей страницы, /imageDetails/:imageRef;
• page — имя целевого экрана, imageDetails;
• title — «Check out my AI image!».

Такую ссылку отправляют в мессенджер или соцсеть, и получатель попадает сразу к этому изображению внутри приложения.

Создание ссылки со страницы, у которой в маршруте лежит идентификатор документа Firebase:

В обработчике handleBranchDeeplink дописывается разбор такой ссылки:

Чтобы переход шёл через глобальный контекст, добавьте перед действием Navigate To действие Execute Custom Code с таким кодом:

final context = appNavigatorKey.currentContext!;

Тогда переход не зависит от того, есть ли ещё главная страница в стеке.

Частые вопросы