ios sdk
v3.0.0
يسمح إطار عمل Spotify iOS لتطبيقك بالتفاعل مع تطبيق Spotify الذي يعمل في الخلفية على جهاز المستخدم. تشمل القدرات الترخيص والحصول على البيانات الوصفية للمسار والسياق الذي يتم تشغيله حاليًا، بالإضافة إلى إصدار أوامر التشغيل.
يرجى ملاحظة: باستخدام أدوات مطور Spotify، فإنك توافق على شروط استخدام المطور الخاصة بنا.
إن Spotify iOS SDK عبارة عن مجموعة من الكائنات خفيفة الوزن التي تتصل بتطبيق Spotify وتتيح لك التحكم فيه أثناء إلغاء تحميل كل عمليات التشغيل الثقيلة إلى تطبيق Spotify نفسه. يعتني تطبيق Spotify بالتشغيل والشبكات والتخزين المؤقت دون الاتصال بالإنترنت وتكامل موسيقى نظام التشغيل، مما يتيح لك التركيز على تجربة المستخدم الخاصة بك. يعد الانتقال من تطبيقك إلى تطبيق Spotify والعكس تجربة مبسطة حيث يظل التشغيل والبيانات التعريفية متزامنين دائمًا.
الميزات الرئيسية
حفظ الأخطاء
عناصر
كيف تعمل مكالمات التطبيق عن بعد؟
شروط الاستخدام
درس تعليمي
الأسئلة المتداولة
نحن نحب تعليقات مجتمع المطورين، لذا لا تتردد في الإبلاغ عن الميزات المفقودة أو الأخطاء في أداة تعقب المشكلات لدينا. تأكد من البحث عن المشكلات الموجودة قبل إنشاء مشكلات جديدة.
تذاكر علة مفتوحة | فتح طلبات الميزات
يتطلب إطار عمل Spotify iOS هدف نشر لنظام التشغيل iOS 12 أو أعلى. يتم دعم البنى التالية في SDK:
SPTAppRemoteAlbumSPTAppRemoteArtistSPTAppRemoteLibraryStateSPTAppRemotePlaybackRestrictionsSPTAppRemotePlaybackOptionsSPTAppRemotePlayerStateSPTAppRemoteTrackSPTAppRemoteContentItemSPTAppRemoteUserCapabilitiesSPTAppRemoteImageRepresentableSPTConfigurationنقطة الدخول الرئيسية للاتصال بتطبيق Spotify واسترداد مكونات API. استخدم هذا لإنشاء الاتصال ومراقبته وإنهائه.
إرسال الأوامر المتعلقة بالتشغيل مثل:
إحضار صورة لـ SPTAppRemoteImageRepresentable
جلب/الاشتراك/تعيين البيانات المتعلقة بالمستخدم مثل:
SPTAppRemoteUserCapabilitiesجلب المحتوى الموصى به للمستخدم.
عندما تتفاعل مع أي من واجهات برمجة تطبيقات App Remote، فإنك تقوم بتمرير كتلة SPTAppRemoteCallback التي يتم استدعاؤها إما باستخدام عنصر النتيجة المتوقعة أو NSError في حالة فشل العملية. يتم تشغيل الحظر بعد استلام تطبيق Spotify الأمر (أو إذا تعذر إجراء الاتصال).
فيما يلي مثال لاستخدام SPTRemotePlayerAPI لتخطي أغنية:
[appRemote.playerAPI skipToNext: ^( id _Nullable result, NSError * _Nullable error) {
if (error) {
// Operation failed
} else {
// Operation succeeded
}
}];نحن نقدم بعض نماذج المشاريع لمساعدتك على البدء باستخدام iOS Framework في مجلد DemoProjects. راجع المستند التمهيدي الموجود في مجلد DemoProjects للحصول على مزيد من المعلومات حول ما تفعله كل عينة.
للتواصل مع تطبيق Spotify، سيحتاج تطبيقك إلى الحصول على إذن المستخدم للتحكم في التشغيل أولاً باستخدام التفويض المضمن لـ App Remote. للقيام بذلك، ستحتاج إلى طلب عرض التفويض عند الاتصال بـ Spotify. سيطلب إطار العمل تلقائيًا نطاق app-remote-control ويعرض عرض المصادقة إذا لم يوافق المستخدم عليه بعد.
لاحظ أنه باستخدام أدوات مطور Spotify، فإنك توافق على شروط استخدام المطور الخاصة بنا.
يرشدك هذا البرنامج التعليمي خطوة بخطوة عبر إنشاء تطبيق بسيط يستخدم Spotify iOS SDK لتشغيل مسار صوتي والاشتراك في حالة المشغل. سوف يسير عبر تدفق التفويض.
اتبع هذه الخطوات للتأكد من أنك مستعد لبدء البرمجة.
أضف حزمة SpotifyiOS إلى مشروعك. يمكنك القيام بذلك إما من خلال Swift Package Manager (SPM)، أو عن طريق إضافة SpotifyiOS.xcframework إلى مشروع Xcode الخاص بك مباشرةً.
في ملف info.plist الخاص بك، قم بإضافة URI الخاص بإعادة التوجيه الذي قمت بتسجيله في تطبيقاتي. ستحتاج إلى إضافة URI الخاص بإعادة التوجيه ضمن "أنواع عناوين URL" و"أنظمة عناوين URL". تأكد من تعيين "معرف URL" فريد أيضًا.
أضف المكتبة إلى ملفاتك المصدرية.
سويفت
import SpotifyiOSالهدف-ج
# import < SpotifyiOS/SpotifyiOS.h > لتتمكن من استخدام جزء التحكم في التشغيل في SDK، يحتاج المستخدم إلى ترخيص التطبيق الخاص بك. إذا لم يحدث ذلك، فسيفشل الاتصال مع ظهور خطأ No token provided . للسماح للمستخدم بتفويض تطبيقك، يمكنك استخدام تدفق التفويض المدمج.
قم بتهيئة SPTConfiguration باستخدام معرف العميل الخاص بك وأعد توجيه URI.
سويفت
let configuration = SPTConfiguration (
clientID : " YOUR_CLIENT_ID " ,
redirectURL : URL ( string : " your_redirect_uri " ) !
)الهدف-ج
SPTConfiguration *configuration = [[SPTConfiguration alloc ] initWithClientID: @" your_client_id "
redirectURL: [ NSURL URLWithString: @" your_redirect_uri " ]]; قم بتهيئة SPTAppRemote باستخدام SPTConfiguration
سويفت
self . appRemote = SPTAppRemote ( configuration : configuration , logLevel : . debug )الهدف-ج
self.appRemote = [[SPTAppRemote alloc ] initWithConfiguration: configuration logLevel: SPTAppRemoteLogLevelDebug];ابدأ عملية المصادقة (للحصول على طرق أخرى لاكتشاف ما إذا كان Spotify مثبتًا، بالإضافة إلى نسب عمليات التثبيت، يرجى الاطلاع على دليل ربط المحتوى الخاص بنا).
سويفت
// Note: A blank string will play the user's last song or pick a random one.
self . appRemote . authorizeAndPlayURI ( " spotify:track:69bp2EbF7Q2rqc5N3ylezZ " ) { spotifyInstalled in
if !spotifyInstalled {
/*
* The Spotify app is not installed.
* Use SKStoreProductViewController with [SPTAppRemote spotifyItunesItemIdentifier] to present the user
* with a way to install the Spotify app.
*/
}
}الهدف-ج
// Note: A blank string will play the user's last song or pick a random one.
[ self .appRemote authorizeAndPlayURI: @" spotify:track:69bp2EbF7Q2rqc5N3ylezZ " completionHandler: ^( BOOL spotifyInstalled) {
if (!spotifyInstalled) {
/*
* The Spotify app is not installed.
* Use SKStoreProductViewController with [SPTAppRemote spotifyItunesItemIdentifier] to present the user
* with a way to install the Spotify app.
*/
}
}]; قم بتكوين AppDelegate الخاص بك لتحليل AccessToken في application:openURL:options: وقم بتعيينه على SPTAppRemote ConnectionParameters.
الهدف-ج
- ( BOOL )application:(UIApplication *)app openURL:( NSURL *)url options:( NSDictionary <UIApplicationOpenURLOptionsKey, id > *)options
{
NSDictionary *params = [ self .appRemote authorizationParametersFromURL: url];
NSString *token = params[SPTAppRemoteAccessTokenKey];
if (token) {
self. appRemote . connectionParameters . accessToken = token;
} else if (params[SPTAppRemoteErrorDescriptionKey]) {
NSLog ( @" %@ " , params[SPTAppRemoteErrorDescriptionKey]);
}
return YES ;
}إذا كنت تستخدم UIScene فأنت بحاجة إلى استخدام الطريقة المناسبة في مندوب المشهد الخاص بك.
سويفت
func scene ( _ scene : UIScene , openURLContexts URLContexts : Set < UIOpenURLContext > ) {
guard let url = URLContexts . first ? . url else {
return
}
let parameters = appRemote . authorizationParameters ( from : url ) ;
if let access_token = parameters ? [ SPTAppRemoteAccessTokenKey ] {
appRemote . connectionParameters . accessToken = access_token
self . accessToken = access_token
} else if let error_description = parameters ? [ SPTAppRemoteErrorDescriptionKey ] {
// Show the error
}
}قم بتعيين مندوب الاتصال الخاص بك وحاول الاتصال.
سويفت
self . appRemote . delegate = self
self . appRemote . connect ( ) // MARK: AppRemoteDelegate
func appRemoteDidEstablishConnection ( _ appRemote : SPTAppRemote ) {
// Connection was successful, you can begin issuing commands
}
func appRemote ( _ appRemote : SPTAppRemote , didFailConnectionAttemptWithError error : Error ? ) {
// Connection failed
}
func appRemote ( _ appRemote : SPTAppRemote , didDisconnectWithError error : Error ? ) {
// Connection disconnected
}الهدف-ج
self.appRemote.delegate = self;
[ self .appRemote connect ];- ( void )appRemoteDidEstablishConnection:(SPTAppRemote *)appRemote
{
// Connection was successful, you can begin issuing commands
}
- ( void )appRemote:(SPTAppRemote *)appRemote didFailConnectionAttemptWithError:( NSError *)error
{
// Connection failed
}
- ( void )appRemote:(SPTAppRemote *)appRemote didDisconnectWithError:(nullable NSError *)error
{
// Connection disconnected
}قم بتعيين مندوب واشترك في حالة اللاعب:
سويفت
self . appRemote . playerAPI ? . delegate = self
appRemote . playerAPI ? . subscribe ( toPlayerState : { result , error in
// Handle Errors
} ) // MARK: SPTAppRemotePlayerStateDelegate
func playerStateDidChange ( _ playerState : SPTAppRemotePlayerState ) {
print ( " track name ( playerState . track . name ) " )
}الهدف-ج
appRemote.playerAPI.delegate = self;
[appRemote.playerAPI subscribeToPlayerState: ^( id _Nullable result, NSError * _Nullable error) {
// Handle Errors
}];- ( void )playerStateDidChange:( id <SPTAppRemotePlayerState>)playerState
{
NSLog ( @" Track name: %@ " , playerState. track . name );
}من باب المجاملة، يجب عليك دائمًا قطع اتصال App Remote عندما يدخل تطبيقك إلى حالة الخلفية. يُخبر هذا Spotify أنه من الآمن تعطيل البث النشط. إذا لم يقم تطبيقك باستدعاء قطع الاتصال بشكل صحيح، فلن يكون لدى Spotify طريقة لمعرفة أنه لا ينبغي له الحفاظ على الاتصال، وقد يؤدي ذلك إلى حدوث مشكلات في الاتصال في المستقبل.
إذا كنت تريد أن يقوم تطبيقك بإعادة الاتصال تلقائيًا بعد أحداث الانقطاع مثل المكالمات الواردة أو تفاعلات Siri، فيمكنك استخدام عمليات رد الاتصال willResignActive و didBecomeActive لقطع الاتصال وإعادة الاتصال بأمان. إذا كنت لا ترغب في إعادة الاتصال مباشرةً، فيكفي عادةً إغلاق الاتصال في عمليات الاسترجاعات didEnterBackground .
سويفت
func sceneWillResignActive ( _ scene : UIScene ) {
self . appRemote . disconnect ( )
}
func sceneDidBecomeActive ( _ scene : UIScene ) {
self . appRemote . connect ( )
}الهدف-ج
- ( void )applicationWillResignActive:(UIApplication *)application
{
[ self .appRemote disconnect ];
}
- ( void )applicationDidBecomeActive:(UIApplication *)application
{
[ self .appRemote connect ];
}
// If you're using UIWindowSceneDelegate
- ( void )sceneDidBecomeActive:(UIScene *)scene
{
[ self .appRemote connect ];
}
- ( void )sceneWillResignActive:(UIScene *)scene
{
[ self .appRemote disconnect ];
} لماذا يجب تشغيل الموسيقى للاتصال بـ SPTAppRemote ؟
يجب تشغيل الموسيقى عند الاتصال بـ SPTAppRemote لضمان عدم تعليق تطبيق Spotify في الخلفية. يمكن لتطبيقات iOS أن تظل نشطة في الخلفية لبضع ثوانٍ فقط ما لم تكن تفعل شيئًا مثل التنقل أو تشغيل الموسيقى.
هل مؤشر ترابط SpotifyiOS.framework آمن؟
لا، يتوقع إطار العمل حاليًا أن يتم استدعاؤه من سلسلة الرسائل الرئيسية. سيتم إلغاء تحميل معظم أعماله إلى سلسلة محادثات في الخلفية داخليًا ولكن سيتم إجراء عمليات رد اتصال للتعليمات البرمجية الخاصة بك أيضًا في سلسلة الرسائل الرئيسية.
ماذا لو كنت بحاجة إلى الترخيص دون بدء التشغيل؟
هناك طريقة ترخيص بديلة. يمكنك العثور على مزيد من المعلومات حول ذلك هنا.
