ایجاد پیوندهای پویا در iOS

بااستفاده از Builder API (میانای برنامه‌سازی کاربردی سازنده) Firebase Dynamic Links می‌توانید Dynamic Links کوتاه یا بلند ایجاد کنید. این میانای برنامه‌سازی کاربردی یا یک Dynamic Link طولانی یا یک شیء حاوی پارامترهای Dynamic Link را می‌پذیرد و نشانی‌های وب را مانند مثال‌های زیر برمی‌گرداند:

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

پیش‌نیازها

قبل‌از شروع، حتماً Firebase را به پروژه iOS خود اضافه کنید.

راه‌اندازی Firebase و کیت توسعه نرم‌افزار Dynamic Links

از Swift Package Manager برای نصب و مدیریت وابستگی‌های Firebase استفاده کنید.

1. در Xcode، درحالی‌که پروژه برنامه‌تان باز است، به File (فایل) > Add Packages (افزودن بسته‌ها) بروید.
2. وقتی خواسته شد، مخزن کیت توسعه نرم‌افزار Firebase برای پلاتفرم‌های Apple را اضافه کنید:

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

3. کتابخانه Dynamic Links را انتخاب کنید.
4. پرچم -ObjC را به بخش Other Linker Flags (سایر پرچم‌های پیونددهنده) در تنظیمات ساخت هدف اضافه کنید.
5. برای داشتن تجربه بهینه با Dynamic Links، توصیه می‌کنیم Google Analytics را در پروژه Firebase خود فعال کنید و کیت توسعه نرم‌افزار Firebase برای Google Analytics را به برنامه‌تان اضافه کنید. می‌توانید کتابخانه را با یا بدون مجموعه IDFA انتخاب کنید. پرسشگان ما را درباره آخرین سازمان‌دهی ماژول‌ها در Google Analytics برای کیت توسعه نرم‌افزار Firebase ببینید.
6. پس‌از اتمام، Xcode به‌طور خودکار شروع به حل و بارگیری وابستگی‌های شما در پس‌زمینه می‌کند.

اکنون، چند مرحله پیکربندی را انجام دهید:

1. در کنسول Firebase، بخش Dynamic Links را باز کنید.

2. اگر قبلاً شرایط خدمات را نپذیرفته‌اید و پیشوند URI برای Dynamic Links تنظیم نکرده‌اید، وقتی از شما خواسته شد این کار را انجام دهید.

   اگر ازقبل پیشوند URI Dynamic Links دارید، آن را یادداشت کنید. باید آن را هنگام ایجاد برنامه‌نویسی‌شده Dynamic Links ارائه دهید.

   

3. توصیه‌شده: الگوهای نشانی وب مجاز در پیوندهای عمیق و پیوندهای بازگشتی را مشخص کنید. با انجام این کار، از ایجاد Dynamic Links توسط طرف‌های غیرمجاز که از دامنه شما به سایت‌هایی که تحت کنترل شما نیستند هدایت می‌کنند جلوگیری می‌کنید. بخش مجاز کردن الگوهای نشانی وب خاص را ببینید.

4. مطمئن شوید که شناسه App Store برنامه و پیشوند شناسه برنامه شما در تنظیمات برنامه‌تان مشخص شده باشد. برای مشاهده و ویرایش تنظیمات برنامه‌تان، به صفحه تنظیمات پروژه Firebase بروید و برنامه iOS خود را انتخاب کنید.

   با باز کردن فایل apple-app-site-association که در دامنه Dynamic Links شما میزبانی می‌شود، تأیید کنید که پروژه Firebase شما به‌درستی برای استفاده از Dynamic Links در برنامه iOS شما پیکربندی شده است. 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 استفاده می‌کنید، باید یک نماینده برنامه ایجاد کنید و آن را ازطریق UIApplicationDelegateAdaptor یا NSApplicationDelegateAdaptor به ساختار App خود متصل کنید. همچنین باید «سویزلینگ نماینده برنامه» را غیرفعال کنید. برای اطلاعات بیشتر، دستورالعمل‌های 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 از پارامترها

برای ایجاد Dynamic Link، شیء DynamicLinkComponents جدیدی ایجاد کنید و پارامترهای Dynamic Link را با تنظیم ویژگی‌های متناظر شیء مشخص کنید. سپس، پیوند طولانی را از ویژگی url شیء دریافت کنید یا با فراخوانی shorten() پیوند کوتاه را دریافت کنید.

مثال حداقلی زیر یک Dynamic Link طولانی برای https://www.example.com/my-page ایجاد می‌کند که با برنامه iOS شما در iOS و برنامه com.example.android در Android باز می‌شود:

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

به‌طور پیش‌فرض، 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);
}];

مشخص کردن طرح‌واره نشانی وب سفارشی برای Dynamic Links

به‌طور پیش‌فرض، Dynamic Links از شناسه دسته نرم‌افزاری برنامه‌تان به‌عنوان طرح‌واره نشانی وب موردنیاز برای باز کردن برنامه‌تان استفاده می‌کند. توصیه می‌کنیم از همین مقدار پیش‌فرض استفاده کنید تا پیاده‌سازی‌تان ساده بماند.

بااین‌حال، توسعه‌دهندگانی که ازقبل از طرح‌واره نشانی وب سفارشی برای اهداف دیگری استفاده می‌کنند ممکن است بخواهند از همین طرح‌واره نشانی وب سفارشی برای Dynamic Links خود نیز استفاده کنند. اگر در این وضعیت هستید، می‌توانید با دنبال کردن این مراحل، طرح‌واره نشانی وب متفاوتی برای Firebase Dynamic Links خود مشخص کنید:

1. هنگام راه‌اندازی برنامه‌تان، مطمئن شوید که طرح‌واره نشانی وب پیش‌فرض را برای استفاده توسط برنامه‌تان مشخص کرده‌اید قبل‌از پیکربندی نمونه مشترک 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 ایجاد می‌کنید، باید طرح‌واره نشانی وب سفارشی را که برنامه‌تان استفاده می‌کند مشخص کنید. می‌توانید این کار را ازطریق کنسول Firebase، تنظیم customScheme در Builder API، مشخص کردن پارامتر ius در نشانی وب، یا ارسال پارامتر iosCustomScheme به REST API انجام دهید

مراحل بعدی

اکنون که Dynamic Links را ایجاد کرده‌اید، باید برنامه‌تان را برای دریافت Dynamic Links و هدایت کاربران به مکان درست در برنامه‌تان پس‌از باز کردن آن‌ها راه‌اندازی کنید.

برای دریافت Dynamic Links در برنامه‌تان، به اسناد مربوط به iOS، Android، C++‎، و Unity مراجعه کنید.