إنشاء روابط ديناميكية على نظام التشغيل iOS

يمكنك إنشاء Dynamic Links قصيرة أو طويلة باستخدام واجهة برمجة التطبيقات Firebase Dynamic Links Builder API. تقبل واجهة برمجة التطبيقات هذه إما مَعلمة Dynamic Link طويلة أو كائنًا يحتوي على مَعلمات Dynamic Link، وتعرض عناوين URL مثل الأمثلة التالية:

https://example.com/link/WXYZ
https://example.page.link/WXYZ

المتطلبات الأساسية

قبل البدء، تأكَّد من إضافة Firebase إلى مشروعك على iOS.

استخدِم Swift Package Manager لتثبيت تبعيات Firebase وإدارتها.

  1. في Xcode، افتح مشروع تطبيقك، ثم انتقِل إلى ملف > إضافة حِزم (File > Add Packages).
  2. عندما يُطلب منك ذلك، أضِف مستودع حزمة تطوير البرامج (SDK) لمنصات Apple من Firebase:
    3.   https://github.com/firebase/firebase-ios-sdk.git
  3. اختَر مكتبة "Dynamic Links".
  4. أضِف العلامة -ObjC إلى قسم علامات الربط الأخرى (Other Linker Flags) في إعدادات إنشاء الهدف.
  5. للحصول على تجربة مثالية مع Dynamic Links، ننصحك بتفعيل Google Analytics في مشروع Firebase وإضافة Firebase SDK لمنصّة إحصاءات Google إلى تطبيقك. يمكنك اختيار المكتبة التي لا تتضمّن ميزة جمع معرّفات المعلِنين (IDFA) أو التي تتضمّنها. يمكنك الاطّلاع على الأسئلة الشائعة حول أحدث تنظيم للوحدات في حزمة تطوير البرامج (SDK) لمنصّة Google Analytics لبرنامج Firebase.
  6. بعد الانتهاء، سيبدأ Xcode تلقائيًا في حلّ التبعيات وتنزيلها في الخلفية.

بعد ذلك، نفِّذ بعض خطوات الضبط:

  1. في وحدة تحكّم Firebase، افتح قسم Dynamic Links.

  2. إذا لم يسبق لك قبول بنود الخدمة وضبط بادئة معرّف الموارد المنتظم (URI) لـ Dynamic Links، يمكنك إجراء ذلك عندما يُطلب منك.

    إذا كان لديك بادئة معرّف موارد منتظم (URI) لـ Dynamic Links، دوِّنها. عليك تقديمها عند إنشاء Dynamic Links آليًا.

  3. إجراء يُنصح به: حدِّد أنماط عناوين URL المسموح بها في الروابط لصفحات معيّنة والروابط الاحتياطية. من خلال إجراء ذلك، يمكنك منع الجهات غير المصرّح لها من إنشاء Dynamic Links تعيد التوجيه من نطاقك إلى مواقع إلكترونية لا تتحكّم فيها. يُرجى الاطّلاع على السماح بأنماط عناوين URL محدّدة.

  4. تأكَّد من تحديد معرّف App Store لتطبيقك وبادئة معرّف التطبيق في إعدادات تطبيقك. لعرض إعدادات تطبيقك وتعديلها، انتقِل إلى صفحة الإعدادات في مشروع Firebase واختَر تطبيق iOS.

    تأكَّد من أنّ مشروع Firebase تم ضبطه بشكلٍ صحيح لاستخدام Dynamic Links في تطبيق iOS من خلال فتح ملف apple-app-site-association المستضاف على نطاق Dynamic Links. ستعرض Firebase ملف apple-app-site-association من جذر النطاق بالإضافة إلى الدليل الفرعي .well-known. على سبيل المثال:

        https://example.com/apple-app-site-association
    https://example.com/.well-known/apple-app-site-association

    إذا كان تطبيقك مرتبطًا، يحتوي ملف apple-app-site-association على مرجع لبادئة معرّف التطبيق ومعرّف الحزمة. على سبيل المثال:

    {"applinks":{"apps":[],"details":[{"appID":"1234567890.com.example.ios","paths":["/*"]}]}}

    إذا كانت السمة details فارغة، تأكَّد من تحديد بادئة معرّف التطبيق. يُرجى العِلم أنّ بادئة رقم تعريف التطبيق قد لا تكون مماثلة لرقم تعريف الفريق.

إضافة Firebase إلى تطبيقك

  1. استورِد وحدة FirebaseCore في UIApplicationDelegate، بالإضافة إلى أي وحدات Firebase أخرى يستخدمها مفوَّض تطبيقك. على سبيل المثال، لاستخدام Cloud Firestore وAuthentication:

    SwiftUI

    import SwiftUI
import FirebaseCore
import FirebaseFirestore
import FirebaseAuth
// ...

    Swift

    import FirebaseCore
import FirebaseFirestore
import FirebaseAuth
// ...

    Objective-C

    @import FirebaseCore;
@import FirebaseFirestore;
@import FirebaseAuth;
// ...
  2. اضبط مثيلاً مشتركًا من النوع FirebaseApp في طريقة application(_:didFinishLaunchingWithOptions:) لمفوَّض تطبيقك:

    SwiftUI

    // Use Firebase library to configure APIs
FirebaseApp.configure()

    Swift

    // Use Firebase library to configure APIs
FirebaseApp.configure()

    Objective-C

    // Use Firebase library to configure APIs
[FIRApp configure];
  3. إذا كنت تستخدم SwiftUI، عليك إنشاء مفوَّض تطبيق وإرفاقه ببنية App من خلال UIApplicationDelegateAdaptor أو NSApplicationDelegateAdaptor. يجب أيضًا إيقاف ميزة "تبديل مفوّض التطبيق". لمزيد من المعلومات، يمكنك الاطّلاع على تعليمات SwiftUI.

    SwiftUI

    @main
struct YourApp: App {
  // register app delegate for Firebase setup
  @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

استخدام وحدة تحكّم Firebase

إذا أردت إنشاء Dynamic Link واحد، إما لأغراض الاختبار أو لفريق التسويق لإنشاء رابط بسهولة يمكن استخدامه في منشور على وسائل التواصل الاجتماعي، فإن أبسط طريقة هي زيارة وحدة تحكّم Firebase وإنشاء رابط يدويًا باتّباع النموذج المفصّل.

استخدام iOS Builder API

يمكنك استخدام iOS Builder API لإنشاء Dynamic Links من المَعلمات أو اختصار Dynamic Link طويل.

لإنشاء Dynamic Link، أنشئ عنصر DynamicLinkComponents جديدًا وحدِّد مَعلمات Dynamic Link من خلال ضبط السمات المقابلة للعنصر. بعد ذلك، يمكنك الحصول على الرابط الطويل من السمة url للعنصر أو الحصول على الرابط القصير من خلال طلب shorten().

ينشئ المثال البسيط التالي رابطًا ديناميكيًا طويلاً من Dynamic Link إلى https://www.example.com/my-page يفتح تطبيق iOS على نظام التشغيل iOS وتطبيق com.example.android على نظام التشغيل Android:

Swift

ملاحظة: لا يتوفّر منتج Firebase هذا على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS. 
guard let link = URL(string: "https://www.example.com/my-page") else { return }
let dynamicLinksDomainURIPrefix = "https://example.com/link"
let linkBuilder = DynamicLinkComponents(link: link, domainURIPrefix: dynamicLinksDomainURIPRefix)
linkBuilder.iOSParameters = DynamicLinkIOSParameters(bundleID: "com.example.ios")
linkBuilder.androidParameters = DynamicLinkAndroidParameters(packageName: "com.example.android")

guard let longDynamicLink = linkBuilder.url else { return }
print("The long URL is: \(longDynamicLink)")

Objective-C

ملاحظة: لا يتوفّر منتج Firebase هذا على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS. 
NSURL *link = [[NSURL alloc] initWithString:@"https://www.example.com/my-page"];
NSString *dynamicLinksDomainURIPrefix = @"https://example.com/link";
FIRDynamicLinkComponents *linkBuilder = [[FIRDynamicLinkComponents alloc]
                                         initWithLink:link
                                               domainURIPrefix:dynamicLinksDomainURIPrefix];
linkBuilder.iOSParameters = [[FIRDynamicLinkIOSParameters alloc]
                             initWithBundleID:@"com.example.ios"];
linkBuilder.androidParameters = [[FIRDynamicLinkAndroidParameters alloc]
                                 initWithPackageName:@"com.example.android"];

NSLog(@"The long URL is: %@", linkBuilder.url);

لإنشاء Dynamic Link قصير، أنشئ DynamicLinkComponents بالطريقة نفسها، ثم استدعِ shorten().

يتطلب إنشاء رابط قصير إجراء مكالمة عبر الشبكة، لذا بدلاً من عرض الرابط مباشرةً، يقبل shorten() معالج إكمال يتم استدعاؤه عند اكتمال الطلب. على سبيل المثال:

Swift

ملاحظة: لا يتوفّر منتج Firebase هذا على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS. 
linkBuilder.shorten() { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

Objective-C

ملاحظة: لا يتوفّر منتج Firebase هذا على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS. 
[linkBuilder shortenWithCompletion:^(NSURL * _Nullable shortURL,
                                     NSArray<NSString *> * _Nullable warnings,
                                     NSError * _Nullable error) {
  if (error || shortURL == nil) { return; }
  NSLog(@"The short URL is: %@", shortURL);
}];

By default, short Dynamic Links are generated with 17-character link suffixes that make it extremely unlikely that someone can guess a valid Dynamic Link. إذا لم يكن هناك ضرر في أن يخمّن شخص ما رابطًا قصيرًا بنجاح في حالة الاستخدام الخاصة بك، قد تفضّل إنشاء لاحقات طويلة بما يكفي لتكون فريدة، ويمكنك إجراء ذلك من خلال ضبط السمة dynamicLinkComponentsOptions:

Swift

ملاحظة: لا يتوفّر منتج Firebase هذا على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS. 
linkBuilder.options = DynamicLinkComponentsOptions()
linkBuilder.options.pathLength = .short
linkBuilder.shorten() { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

Objective-C

ملاحظة: لا يتوفّر منتج Firebase هذا على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS. 
linkBuilder.dynamicLinkComponentsOptions = [[FIRDynamicLinkComponentsOptions alloc] init];
linkBuilder.dynamicLinkComponentsOptions.pathLength = FIRShortDynamicLinkPathLengthShort;
[linkBuilder shortenWithCompletion:^(NSURL * _Nullable shortURL,
                                     NSArray<NSString *> * _Nullable warnings,
                                     NSError * _Nullable error) {
  if (error || shortURL == nil) { return; }
  NSLog(@"The short URL is: %@", shortURL);
}];

يمكنك استخدام واجهة برمجة التطبيقات Dynamic Link Builder API لإنشاء Dynamic Links باستخدام أي من المَعلمات المتوافقة. لمزيد من التفاصيل، يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات.

ينشئ المثال التالي Dynamic Link مع ضبط عدة مَعلمات شائعة:

Swift

ملاحظة: لا يتوفّر منتج Firebase هذا على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS. 
guard let link = URL(string: "https://www.example.com/my-page") else { return }
let dynamicLinksDomainURIPrefix = "https://example.com/link"
let linkBuilder = DynamicLinkComponents(link: link, domainURIPRefix: dynamicLinksDomainURIPrefix)

linkBuilder.iOSParameters = DynamicLinkIOSParameters(bundleID: "com.example.ios")
linkBuilder.iOSParameters.appStoreID = "123456789"
linkBuilder.iOSParameters.minimumAppVersion = "1.2.3"

linkBuilder.androidParameters = DynamicLinkAndroidParameters(packageName: "com.example.android")
linkBuilder.androidParameters.minimumVersion = 123

linkBuilder.analyticsParameters = DynamicLinkGoogleAnalyticsParameters(source: "orkut",
                                                                       medium: "social",
                                                                       campaign: "example-promo")

linkBuilder.iTunesConnectParameters = DynamicLinkItunesConnectAnalyticsParameters()
linkBuilder.iTunesConnectParameters.providerToken = "123456"
linkBuilder.iTunesConnectParameters.campaignToken = "example-promo"

linkBuilder.socialMetaTagParameters = DynamicLinkSocialMetaTagParameters()
linkBuilder.socialMetaTagParameters.title = "Example of a Dynamic Link"
linkBuilder.socialMetaTagParameters.descriptionText = "This link works whether the app is installed or not!"
linkBuilder.socialMetaTagParameters.imageURL = "https://www.example.com/my-image.jpg"

guard let longDynamicLink = linkBuilder.url else { return }
print("The long URL is: \(longDynamicLink)")

Objective-C

ملاحظة: لا يتوفّر منتج Firebase هذا على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS. 
NSURL *link = [[NSURL alloc] initWithString:@"https://www.example.com/my-page"];
NSString *dynamicLinksDomainURIPrefix = @"https://example.com/link";
FIRDynamicLinkComponents *linkBuilder = [[FIRDynamicLinkComponents alloc]
                                         initWithLink:link
                                         domainURIPrefix:dynamicLinksDomainURIPrefix];

linkBuilder.iOSParameters = [[FIRDynamicLinkIOSParameters alloc]
                             initWithBundleID:@"com.example.ios"];
linkBuilder.iOSParameters.appStoreID = @"123456789";
linkBuilder.iOSParameters.minimumAppVersion = @"1.2.3";

linkBuilder.androidParameters = [[FIRDynamicLinkAndroidParameters alloc]
                                 initWithPackageName:@"com.example.android"];
linkBuilder.androidParameters.minimumVersion = 123;

linkBuilder.analyticsParameters = [[FIRDynamicLinkGoogleAnalyticsParameters alloc]
                                   initWithSource:@"orkut"
                                           medium:@"social"
                                         campaign:@"example-promo"];

linkBuilder.iTunesConnectParameters = [[FIRDynamicLinkItunesConnectAnalyticsParameters alloc] init];
linkBuilder.iTunesConnectParameters.providerToken = @"123456";
linkBuilder.iTunesConnectParameters.campaignToken = @"example-promo";

linkBuilder.socialMetaTagParameters = [[FIRDynamicLinkSocialMetaTagParameters alloc] init];
linkBuilder.socialMetaTagParameters.title = @"Example of a Dynamic Link";
linkBuilder.socialMetaTagParameters.descriptionText = @"This link works whether the app is installed or not!";
linkBuilder.socialMetaTagParameters.imageURL = @"https://www.example.com/my-image.jpg";

NSLog(@"The long URL is: %@", linkBuilder.url);

يمكنك ضبط مَعلمات Dynamic Link باستخدام العناصر والسمات التالية:

DynamicLinkComponents
الرابط

الرابط الذي سيفتحه تطبيقك حدِّد عنوان URL يمكن لتطبيقك معالجته، ويكون عادةً محتوى التطبيق أو حمولته، والذي يبدأ منطقًا خاصًا بالتطبيق (مثل منح المستخدم قسيمة أو عرض شاشة ترحيب). يجب أن يكون هذا الرابط عنوان URL منسَّقًا بشكل جيد، وأن يكون بترميز عنوان URL بشكل صحيح، وأن يستخدم إما HTTP أو HTTPS، ولا يمكن أن يكون رابطًا ديناميكيًا آخر.
domainURIPrefix بادئة عنوان URL لـ Dynamic Link، والتي يمكنك العثور عليها في وحدة تحكّم Firebase يبدو نطاق Dynamic Link مثل الأمثلة التالية: 
https://example.com/link
https://example.page.link
DynamicLinkAndroidParameters
fallbackURL الرابط الذي يتم فتحه في حال عدم تثبيت التطبيق حدِّد هذا الإجراء لتنفيذ إجراء آخر غير تثبيت تطبيقك من "متجر Google Play" عندما لا يكون التطبيق مثبَّتًا، مثل فتح نسخة الويب على الأجهزة الجوّالة من المحتوى أو عرض صفحة ترويجية لتطبيقك.
minimumVersion ‫versionCode الحد الأدنى لإصدار تطبيقك الذي يمكنه فتح الرابط إذا كان التطبيق المثبّت إصدارًا قديمًا، يتم توجيه المستخدم إلى "متجر Google Play" لترقية التطبيق.
DynamicLinkIOSParameters
appStoreID معرّف متجر التطبيقات لتطبيقك، ويُستخدم لإرسال المستخدمين إلى متجر التطبيقات عندما لا يكون التطبيق مثبّتًا
fallbackURL الرابط الذي يتم فتحه في حال عدم تثبيت التطبيق حدِّد هذا الخيار لتنفيذ إجراء آخر غير تثبيت تطبيقك من App Store عندما لا يكون التطبيق مثبّتًا، مثل فتح إصدار الويب على الأجهزة الجوّالة من المحتوى أو عرض صفحة ترويجية لتطبيقك.
customScheme مخطّط URL مخصّص لتطبيقك، إذا تم تحديده ليكون مختلفًا عن معرّف الحزمة لتطبيقك
iPadFallbackURL الرابط الذي يتم فتحه على أجهزة iPad في حال عدم تثبيت التطبيق حدِّد هذا الخيار لتنفيذ إجراء آخر غير تثبيت تطبيقك من App Store عندما لا يكون التطبيق مثبّتًا، مثل فتح إصدار الويب من المحتوى أو عرض صفحة ترويجية لتطبيقك.
iPadBundleID معرّف حزمة تطبيق iOS الذي سيتم استخدامه على أجهزة iPad لفتح الرابط يجب ربط التطبيق بمشروعك من صفحة "نظرة عامة" في وحدة تحكّم "Firebase".
minimumAppVersion رقم الإصدار للحد الأدنى من إصدار تطبيقك الذي يمكنه فتح الرابط يتم تمرير هذه العلامة إلى تطبيقك عند فتحه، ويجب أن يقرّر تطبيقك الإجراء الذي يجب اتّخاذه بشأنها.
DynamicLinkNavigationInfoParameters
forcedRedirectEnabled في حال ضبط السياسة على "1"، يتم تخطّي صفحة معاينة التطبيق عند فتح Dynamic Link، وبدلاً من ذلك تتم إعادة التوجيه إلى التطبيق أو المتجر. يمكن لصفحة معاينة التطبيق (المفعَّلة تلقائيًا) إرسال المستخدمين بشكل أكثر موثوقية إلى الوجهة الأنسب عند فتح Dynamic Links في التطبيقات. ومع ذلك، إذا كنت تتوقّع فتح Dynamic Link فقط في التطبيقات التي يمكنها فتح Dynamic Links بشكل موثوق بدون هذه الصفحة، يمكنك إيقافها باستخدام هذه المَعلمة. ستؤثر هذه المَعلمة في سلوك Dynamic Link على أجهزة iOS فقط.
DynamicLinkSocialMetaTagParameters
العنوان العنوان الذي سيتم استخدامه عند مشاركة Dynamic Link في منشور على شبكات التواصل الاجتماعي
descriptionText الوصف الذي سيتم استخدامه عند مشاركة Dynamic Link في منشور على شبكات التواصل الاجتماعي
imageURL عنوان URL لصورة مرتبطة بهذا الرابط يجب أن يكون حجم الصورة 300×200 بكسل على الأقل، وأقل من 300 كيلوبايت.
DynamicLinkGoogleAnalyticsParameters
source
medium
campaign
term
content		 مَعلمات إحصاءات Google Play يتم تمرير هذه المَعلمات (utm_source وutm_medium وutm_campaign وutm_term وutm_content) إلى "متجر Google Play"، كما يتم إلحاقها بحمولة الرابط.
DynamicLinkItunesConnectAnalyticsParameters
providerToken
affiliateToken
campaignToken		 مَعلمات إحصاءات iTunes Connect يتم تمرير هذه المَعلمات (pt وat وct) إلى متجر التطبيقات.

لاختصار Dynamic Link طويل، مرِّر Dynamic Link الطويل إلى shortenURL(url:options:) مع عنصر DynamicLinkComponentsOptions إذا أردت إنشاء رابط بلاحقة قصيرة:

Swift

ملاحظة: لا يتوفّر منتج Firebase هذا على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS. 
DynamicLinkComponents.shortenURL(url: longLinkUrl, options: nil) { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

Objective-C

ملاحظة: لا يتوفّر منتج Firebase هذا على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS. 
[FIRDynamicLinkComponents shortenURL:longLinkUrl
                             options:nil
                          completion:^(NSURL * _Nullable shortURL,
                                       NSArray<NSString *> * _Nullable warnings,
                                       NSError * _Nullable error) {
  if (error || shortURL == nil) { return; }
  NSLog(@"The short URL is: %@", shortURL);
}];

يستخدم Dynamic Links تلقائيًا معرّف حزمة تطبيقك كمخطّط عنوان URL اللازم لفتح تطبيقك. ننصحك بالالتزام بهذه القيمة التلقائية للحفاظ على بساطة عملية التنفيذ.

ومع ذلك، قد يرغب المطوّرون الذين يستخدمون حاليًا مخطّط URL مخصّصًا لأغراض أخرى في استخدام مخطّط URL المخصّص نفسه لـ Dynamic Links أيضًا. إذا كنت في هذه الحالة، يمكنك تحديد مخطّط URL مختلف لـ Firebase Dynamic Links باتّباع الخطوات التالية:

  1. عند إعداد تطبيقك، تأكَّد من تحديد مخطّط عنوان URL التلقائي الذي سيستخدمه تطبيقك قبل ضبط مثيل FirebaseApp المشترَك:

    Swift

    ملاحظة: لا يتوفّر منتج Firebase هذا على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS. 
    func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication
                   .LaunchOptionsKey: Any]?) -> Bool {
  // Set deepLinkURLScheme to the custom URL scheme you defined in your
  // Xcode project.
  FirebaseOptions.defaultOptions()?.deepLinkURLScheme = customURLScheme
  FirebaseApp.configure()

  return true
}

    Objective-C

    ملاحظة: لا يتوفّر منتج Firebase هذا على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS. 
    - (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // Set deepLinkURLScheme to the custom URL scheme you defined in your
  // Xcode project.
  [FIROptions defaultOptions].deepLinkURLScheme = CUSTOM_URL_SCHEME;
  [FIRApp configure];

  return YES;
}
  2. عند إنشاء أي Dynamic Link، عليك تحديد مخطّط عنوان URL المخصّص الذي يستخدمه تطبيقك. يمكنك إجراء ذلك من خلال وحدة تحكّم Firebase، أو ضبط customScheme في Builder API، أو تحديد مَعلمة ius في عنوان URL، أو إرسال مَعلمة iosCustomScheme إلى REST API

الخطوات التالية

بعد إنشاء Dynamic Links، عليك إعداد تطبيقك لتلقّي Dynamic Links وتوجيه المستخدمين إلى المكان المناسب في تطبيقك بعد أن يفتحها المستخدم.

لتلقّي Dynamic Links في تطبيقك، اطّلِع على مستندات iOS وAndroid وC++‎ وUnity.