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

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

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

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

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

إعداد Firebase و‫حزمة تطوير البرامج (SDK) لـ Dynamic Links

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

1. في Xcode، افتح مشروع تطبيقك وانتقِل إلى ملف > إضافة حِزم.
2. عند المطالبة بذلك، أضِف مستودع حزمة تطوير البرامج (SDK) لمنصّات Firebase Apple:

  https://github.com/firebase/firebase-ios-sdk.git

3. اختَر مكتبة Dynamic Links.
4. أضِف العلامة -ObjC إلى قسم علامات الرابط الأخرى في إعدادات الإصدار لهدفك.
5. لتحقيق أفضل تجربة مع Dynamic Links، ننصحك بتفعيل Google Analytics في مشروع Firebase وإضافة Firebase SDK لخدمة "إحصاءات Google" إلى تطبيقك. يمكنك اختيار المكتبة بدون جمع معرّف المعلِنين (IDFA) أو مع جمع معرّف المعلِنين (IDFA). راجِع الأسئلة الشائعة حول الـ أحدث تنظيم للوحدات في الـ Google Analytics لحزمة تطوير البرامج (SDK) من 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. استورِد الو0/ الوحدة في101 1/، بالإضافة إلى أي101 2وحدات Firebase3/ أخرى يستخدمها مفوّض تطبيقك.FirebaseCoreUIApplicationDelegate على سبيل المثال، لاستخدام 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. اضبط مثيلاً مشتركًا في طريقة application(_:didFinishLaunchingWithOptions:) لمفوّض تطبيقك:FirebaseApp

   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 console وإنشاء رابط يدويًا باتّباع النموذج المفصّل.

استخدام iOS Builder API

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

إنشاء Dynamic Link من المَعلمات

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

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

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)")

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() معالج إكمال يتم استدعاؤه عند اكتمال الطلب. على سبيل المثال:

linkBuilder.shorten() { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

[linkBuilder shortenWithCompletion:^(NSURL * _Nullable shortURL,
                                     NSArray<NSString *> * _Nullable warnings,
                                     NSError * _Nullable error) {
  if (error || shortURL == nil) { return; }
  NSLog(@"The short URL is: %@", shortURL);
}];
      

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

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)")
}

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

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

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

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)")

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 باستخدام الكائنات والخصائص التالية:

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

تقصير رابط طويل Dynamic Link

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

DynamicLinkComponents.shortenURL(url: longLinkUrl, options: nil) { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

[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);
}];

تحديد مخطّط عنوان URL مخصّص لـ Dynamic Links

تستخدم 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.