إنشاء روابط ديناميكية على نظام التشغيل 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 إلى القسم علامات الروابط الأخرى في إعدادات إصدار هدفك.
  5. للحصول على تجربة مثالية مع Dynamic Links، ننصحك بتفعيل Google Analytics في مشروعك على Firebase وإضافة حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google لبرنامج Firebase" إلى تطبيقك. ويمكنك اختيار المكتبة بدون جمع معرّف جهاز IDFA أو مع جمع معرّف جهاز IDFA.
  6. عند الانتهاء، سيبدأ Xcode تلقائيًا في حلّ ملفاتك المضمّنة وتنزيلها في الخلفية.

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

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

  2. إذا لم يسبق لك قبول بنود الخدمة وضبط بادئة عنوان URL لـ Dynamic Links، يُرجى إجراء ذلك عندما يُطلب منك ذلك.

    إذا كان لديك بادئة Dynamic Links URI، دوِّنها. يجب تقديمه عند إنشاء 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);
}];

يتم تلقائيًا إنشاء Dynamic Links قصيرة باستخدام لاحقات روابط تتألف من 17 حرفًا، ما يجعل من غير المرجّح أن يخمن أحد المستخدمين 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 باستخدام العناصر والسمات التالية:

مكونات DynamicLink
الرابط

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

لتقصير 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.

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

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

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