Cihaz Ayrıntılarını Alma

AIBuds cihazında şu anda kullanılabilir olan bilgileri okuyun. Cihaz ayrıntıları cihaz nesnesinin özellikleri olarak sunulur; tek bir getDeviceDetails isteği veya DeviceDetails sonuç modeli yoktur.

Kimlik, firmware, bağlantı ve yayın bilgileri için DeviceConvertible kullanın. Cihaz ayrıca DeviceInfoAPI protokolüne uyuyorsa pil durumunu, bildirilen yetenekleri, donanım yapılandırmasını, dil ayarını, arama durumunu, depolama bilgisini ve medya sayılarını okuyabilirsiniz.

Ön Koşullar

Cihaz ayrıntılarını okumadan önce:

• Tarama, saklanan cihaz veya bağlantı akışınızdan bir DeviceConvertible örneği elde edin.
• Cihazın bildirdiği en güncel değerlere gereksinim duyuyorsanız cihaz bağlanıp hazır olana kadar bekleyin.
• İsteğe bağlı özellikleri, SDK veya cihaz değer sağlayana kadar kullanılamıyor olarak değerlendirin.

:::info Geçerli anlık görüntü Bu özellikleri okumak Bluetooth komutu göndermez. Değerler SDK’nın geçerli anlık görüntüsünü temsil eder; keşif verilerinden, kalıcı cihaz verilerinden veya etkin bağlantı sırasında alınan bilgilerden gelebilir. :::

API Referansı

Framework

AIBuds.xcframework

İçe Aktarma

SDK’yı kullanacağınız dosyalarda ana framework’ü içe aktarın:

Swift

Swift

import AIBuds

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

Protokol

Cihaz ayrıntıları iki protokolle sunulur. DeviceConvertible temel cihaz anlık görüntüsünü, DeviceInfoAPI ise bağlı cihaz bu protokolü desteklediğinde ek cihaz bilgisi özelliklerini sağlar.

Swift

Swift

/// Defines the persistent identity and capabilities of an AIBuds device.
protocol DeviceConvertible: NSObjectProtocol, NSSecureCoding

/// The protocol for device information related API.
protocol DeviceInfoAPI: DeviceAPI

Objective-C

Objective-C

/// Defines the persistent identity and capabilities of an AIBuds device.
@protocol AIBudsDeviceConvertible <NSSecureCoding, NSObject>

/// The protocol for device information related API.
@protocol AIBudsDeviceInfoAPI <AIBudsDeviceAPI>

Özellikler

Temel cihaz özellikleri

Bu özelliklere DeviceConvertible üzerinden erişilir.

Kategori	Özellikler	Notlar
Kimlik	name, uuid, bluetoothName, macAddress, product	SDK’nın şu anda bildiği cihaz adı ve tanımlayıcıları.
Donanım	deviceModel, deviceSerialNum, formatedProjNumber	Desteklenen cihazların bildirdiği isteğe bağlı değerler.
Firmware	firmwareVersion, formatedFirmwareVersion, coProcessorFirmwareVersion	formatedFirmwareVersion, Demo’nun gösterim için kullandığı ana firmware dizesidir.
Bağlantı	connectionState, deviceState, isConnectedAndReady, isBusy, lastConnectTime	Canlı cihaz durumuna güvenmeden önce isConnectedAndReady kullanın.
Bağlama	bindUserId, userBindTime, isAlreadyUnbind, shouldAutoReconnectWhenAppLaunch	SDK’nın yönettiği bağlama ve yeniden bağlantı durumu.
Yayın	advertisementDataString, advertisementRawData, manufacturerData, manufacturerHexDataString, timestampOfAdvertisementData	En son alınan yayın verilerinden türetilen değerler.
Sunum	thumbnail, screenName, customContent	Ana uygulamanın kullanıcı arayüzünde kullanabileceği isteğe bağlı değerler.

Cihaz bilgisi özellikleri

DeviceInfoAPI uyumluluğunu doğruladıktan sonra aşağıdaki ek anlık görüntü değerlerine erişebilirsiniz.

Özellik	Tür	Açıklama
batteryStatusInfo	BatteryStatusModel?	Cihazın pil bileşenlerine ait gerçek zamanlı bilgiler.
deviceCapabilities	DeviceCapabilities?	Cihazın bildirdiği normalleştirilmiş yetenek bayrakları; geçerli bilgi alınana kadar nil.
hardwareConfiguration	DeviceHardwareConfiguration	Cihazın bildirdiği fiziksel giriş donanımı ve cihaz üzerindeki yönlendirme gereksinimleri.
languageSetting	DeviceLanguage	Geçerli cihaz dili.
supportedLanguages	[NSNumber]	Cihazın desteklediği ham DeviceLanguage değerleri.
callStatus	CallStatus	Geçerli arama durumu.
storageInfo	StorageInfoModel?	MB cinsinden kullanılan ve boş depolama alanı.
mediaCountInfo	MediaCountInfoModel?	Fotoğraf, video ve ses dosyası sayıları.
isSupportAdjustRecordDuration	Bool	Maksimum kayıt süresinin yapılandırılabilir olup olmadığı.
aiSolutionCapabilities	AIBudsAISolutionCapabilities	Cihazın bildirdiği AI yetenekleri.
coprocessorModel	CoprocessorModel	Cihazın yardımcı işlemci modeli.
imageEnhancementPostProcessingAlgorithm	ImageEnhancementPostProcessingAlgorithm	Cihazın bildirdiği geçerli görüntü iyileştirme son işleme algoritması; varsayılan .general.
recommendedMaxVideoRecordingDurationOptions	[NSNumber]	Önerilen maksimum video kayıt süresi seçenekleri dakika cinsindendir; varsayılan [1, 3, 9, 12].
recommendedMaxAudioRecordingDurationOptions	[NSNumber]	Önerilen maksimum ses kayıt süresi seçenekleri dakika cinsindendir; varsayılan [30, 60, 120].
minimumBatteryLevelForMediaOperations	Int	Fotoğraf, video, ses ve dosya aktarımı için minimum pil yüzdesi; varsayılan 30. OTA ayrı kurallar kullanır.

Yaygın durum değerleri

batteryStatusInfo, ürünün desteklediği herhangi bir bileşeni içerebilir:

BatteryComponent	Anlamı
.glass	Gözlük gövdesi
.leftEarbud / .rightEarbud	Sol veya sağ kulaklık
.chargingCase	Şarj kutusu
.mainSpeaker / .sideSpeaker	Ana veya yan hoparlör
.headphones	Kulak üstü kulaklık
.unknown	Bileşen kullanılamıyor veya tanınmıyor

TWS, uzamsal ses, çoklu bağlantı, ANC, cihaz üzerindeki sesli asistan, bas motoru, canlı yayın, Ximalaya ve fabrika testi uyarı sesini sunup sunmamaya deviceCapabilities alanlarıyla karar verin. Bu özellikleri yalnızca product değerinden çıkarmayın. nil, geçerli yetenek bilgisinin henüz alınmadığını gösterir; tüm özelliklerin desteklenmediği anlamına gelmez.

hardwareConfiguration, ürünün nasıl kullanılabileceğini açıklar:

Özellik	Anlamı
hasTouchInput	Dokunmatik giriş yüzeyi vardır.
hasPhysicalButtonInput	Fiziksel düğme girişi vardır.
requiresOnDeviceVoiceAssistantGuidance	Ana uygulama, cihaz üzerindeki sesli asistan için kullanım yönlendirmesi sunmalıdır.

callStatus, CallStatus kullanır:

Değer	Anlamı
.notInCall	Etkin arama yoktur.
.ringing	Gelen arama çalıyor.
.inCall	Arama etkindir.
.threeWayRinging	Desteklendiğinde üç yönlü arama çalıyor.
.aiChat	Cihaz, geçerli arama kanalı etkinliği olarak AI görüşmesini bildiriyor.
.unknown	Arama durumu kullanılamıyor veya tanınmıyor.

Kullanım Örnekleri

Cihaz Ayrıntılarını Okuma

Aşağıdaki örnekler SDK Demo’sundaki DeviceInfoDetailsController ile aynı yaklaşımı izler: önce temel cihaz özelliklerini okuyun, ardından koşullu olarak DeviceInfoAPI özelliklerini ekleyin.

Swift

Swift

import AIBuds

typealias DeviceDetail = (label: String, value: String)

func formattedDate(_ date: Date?, unavailable: String) -> String {
    guard let date else { return unavailable }

    let formatter = DateFormatter()
    formatter.dateStyle = .medium
    formatter.timeStyle = .medium
    return formatter.string(from: date)
}

func deviceDetails(for device: DeviceConvertible) -> [DeviceDetail] {
    let unavailable = "N/A"
    var details: [DeviceDetail] = [
        ("Device Name", device.name),
        ("UUID", device.uuid.uuidString),
        ("Bluetooth Name", device.bluetoothName ?? unavailable),
        ("MAC Address", device.macAddress ?? unavailable),
        ("Product", String(describing: device.product)),
        ("Device Model", device.deviceModel ?? unavailable),
        ("Serial Number", device.deviceSerialNum ?? unavailable),
        ("Firmware Version", device.formatedFirmwareVersion ?? unavailable),
        ("Co-processor Firmware", device.coProcessorFirmwareVersion ?? unavailable),
        ("Project Number", device.formatedProjNumber ?? unavailable),
        ("Last Connection", formattedDate(device.lastConnectTime, unavailable: unavailable)),
        ("Auto Reconnect", device.shouldAutoReconnectWhenAppLaunch ? "Yes" : "No"),
        ("Advertisement Data", device.advertisementDataString ?? unavailable),
        ("Manufacturer Data", device.manufacturerHexDataString ?? unavailable),
        (
            "Advertisement Timestamp",
            formattedDate(device.timestampOfAdvertisementData, unavailable: unavailable)
        ),
        ("Screen Name", device.screenName ?? unavailable),
        ("Custom Content", device.customContent ?? unavailable),
    ]

    guard let info = device as? DeviceInfoAPI else {
        return details
    }

    let supportedLanguages = info.supportedLanguages
        .compactMap { DeviceLanguage(rawValue: $0.intValue) }
        .map { String(describing: $0) }
        .joined(separator: ", ")

    details.append(contentsOf: [
        ("Battery Status", info.batteryStatusInfo?.description ?? unavailable),
        ("Device Capabilities", info.deviceCapabilities?.description ?? unavailable),
        ("Hardware Configuration", info.hardwareConfiguration.description),
        ("Language", String(describing: info.languageSetting)),
        ("Supported Languages", supportedLanguages.isEmpty ? unavailable : supportedLanguages),
        ("Call Status", String(describing: info.callStatus)),
        ("Storage", info.storageInfo?.description ?? unavailable),
        ("Media Count", info.mediaCountInfo?.description ?? unavailable),
        ("Adjustable Recording Duration", info.isSupportAdjustRecordDuration ? "Yes" : "No"),
        ("AI Capabilities", String(describing: info.aiSolutionCapabilities)),
        ("Co-processor Model", String(describing: info.coprocessorModel)),
        (
            "Image Enhancement",
            String(describing: info.imageEnhancementPostProcessingAlgorithm)
        ),
        ("Recommended Video Duration Options", info.recommendedMaxVideoRecordingDurationOptions.description),
        ("Recommended Audio Duration Options", info.recommendedMaxAudioRecordingDurationOptions.description),
        ("Minimum Media Battery", "\(info.minimumBatteryLevelForMediaOperations)%"),
    ])

    return details
}

Objective-C

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

- (NSArray<NSDictionary<NSString *, NSString *> *> *)deviceDetailsForDevice:
    (id<AIBudsDeviceConvertible>)device {
    NSString *unavailable = @"N/A";
    NSMutableArray<NSDictionary<NSString *, NSString *> *> *details = [NSMutableArray array];

    void (^addDetail)(NSString *, id _Nullable) = ^(NSString *label, id _Nullable value) {
        [details addObject:@{
            @"label" : label,
            @"value" : value ? [value description] : unavailable,
        }];
    };

    addDetail(@"Device Name", device.name);
    addDetail(@"UUID", device.uuid.UUIDString);
    addDetail(@"Bluetooth Name", device.bluetoothName);
    addDetail(@"MAC Address", device.macAddress);
    addDetail(@"Product", @(device.product));
    addDetail(@"Device Model", device.deviceModel);
    addDetail(@"Serial Number", device.deviceSerialNum);
    addDetail(@"Firmware Version", device.formatedFirmwareVersion);
    addDetail(@"Co-processor Firmware", device.coProcessorFirmwareVersion);
    addDetail(@"Project Number", device.formatedProjNumber);
    addDetail(@"Last Connection", device.lastConnectTime);
    addDetail(@"Auto Reconnect", device.shouldAutoReconnectWhenAppLaunch ? @"Yes" : @"No");
    addDetail(@"Advertisement Data", device.advertisementDataString);
    addDetail(@"Manufacturer Data", device.manufacturerHexDataString);
    addDetail(@"Advertisement Timestamp", device.timestampOfAdvertisementData);
    addDetail(@"Screen Name", device.screenName);
    addDetail(@"Custom Content", device.customContent);

    id<AIBudsDeviceInfoAPI> info = (id<AIBudsDeviceInfoAPI>)device;
    if ([info conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
        addDetail(@"Battery Status", info.batteryStatusInfo);
        addDetail(@"Device Capabilities", info.deviceCapabilities);
        addDetail(@"Hardware Configuration", info.hardwareConfiguration);
        addDetail(@"Language", @(info.languageSetting));
        addDetail(@"Supported Languages", info.supportedLanguages);
        addDetail(@"Call Status", @(info.callStatus));
        addDetail(@"Storage", info.storageInfo);
        addDetail(@"Media Count", info.mediaCountInfo);
        addDetail(@"Adjustable Recording Duration",
                  info.isSupportAdjustRecordDuration ? @"Yes" : @"No");
        addDetail(@"AI Capabilities", @(info.aiSolutionCapabilities));
        addDetail(@"Co-processor Model", @(info.coprocessorModel));
        addDetail(@"Image Enhancement", @(info.imageEnhancementPostProcessingAlgorithm));
        addDetail(@"Recommended Video Duration Options", info.recommendedMaxVideoRecordingDurationOptions);
        addDetail(@"Recommended Audio Duration Options", info.recommendedMaxAudioRecordingDurationOptions);
        addDetail(@"Minimum Media Battery",
                  [NSString stringWithFormat:@"%ld%%",
                                             (long)info.minimumBatteryLevelForMediaOperations]);
    }

    return details;
}

Döndürülen satırları uygulamanızın kendi görünüm modeli ve yerelleştirmesiyle gösterin. Demo bir tablo görünümü kullanır ve enum değerlerini yerelleştirilmiş gösterim metnine dönüştürür.

Depolama veya Medya Bilgisini Yenileme

storageInfo ve mediaCountInfo anlık görüntü özellikleridir. Ekranınız güncel değer gerektiriyorsa önce güncelleme isteyin, işlem başarılı olduktan sonra ilgili özelliği okuyun.

Swift

Swift

guard let info = device as? DeviceInfoAPI else { return }

info.requestQueryStorageInfo { success, error in
    guard success else {
        print(error?.localizedDescription ?? "Storage query failed")
        return
    }

    print(info.storageInfo?.description ?? "Storage information is unavailable")
}

Objective-C

Objective-C

id<AIBudsDeviceInfoAPI> info = (id<AIBudsDeviceInfoAPI>)self.device;
if ([info conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
    [info requestQueryStorageInfoWithCompletion:^(BOOL success, NSError *_Nullable error) {
        if (!success) {
            NSLog(@"Storage query failed: %@", error.localizedDescription);
            return;
        }

        NSLog(@"%@", info.storageInfo);
    }];
}

Swift’te requestQueryMediaCountInfo(_:), Objective-C’de requestQueryMediaCountInfoWithCompletion: çağırarak mediaCountInfo değerini yenileyin.

Hata Yönetimi

Özellik erişimi eşzamansız hata döndürmez. Açık yenileme işlemleri hataları completion işleyicileri aracılığıyla bildirir. Kullanılamayan bilgileri şöyle yönetin:

1. Canlı değerler gerektiğinde device.isConnectedAndReady durumunu denetleyin.
2. DeviceInfoAPI özelliklerini okumadan önce protokol uyumluluğunu doğrulayın.
3. Her cihaz modelinin tüm değerleri bildirdiğini varsaymadan isteğe bağlı özellikleri yönetin; nil olan deviceCapabilities değerini desteklenmiyor değil bilinmiyor olarak değerlendirin.
4. Yayın alanlarını en son alınan yayın anlık görüntüsü olarak değerlendirin.
5. Depolama veya medya sayısı sorguları gibi açık yenileme işlemlerinde success ve error değerlerini yönetin.

En İyi Uygulamalar

1. Protokol Uyumluluğunu Denetleyin: Genişletilmiş özellikleri okumadan önce DeviceInfoAPI desteğini doğrulayın.

2. Bildirilen Değerlerle Sınırlandırın: Ürün adı veya sabit sınırlar yerine deviceCapabilities bayraklarını, önerilen kayıt sürelerini ve minimumBatteryLevelForMediaOperations değerini kullanın.

3. Değerleri Anlık Görüntü Olarak Değerlendirin: Tüm özelliklerin aynı anda yenilendiğini varsaymayın.

4. İsteğe Bağlı Değerleri Yönetin: Varsayımsal cihaz verisi üretmek yerine kullanılamıyor durumunu gösterin.

5. Yalnızca Gerektiğinde Yenileyin: Ekran güncel değer gerektirdiğinde depolama ve medya sayısı sorgu yöntemlerini kullanın.

6. Gösterim Değerlerini Yerelleştirin: Ürün, dil, arama durumu ve diğer enum değerlerini kullanıcıya uygun yerelleştirilmiş metne dönüştürün.

Notlar

• Cihaz yetenekleri ve kullanılabilir alanlar ürüne ve firmware’e göre değişir. DeviceProduct.headphones kulak üstü kulaklık ürününü, BatteryComponent.headphones ise pil girdisini belirtir.
• supportedLanguages, NSNumber biçiminde DeviceLanguage.rawValue değerlerini içerir.
• StorageInfoModel, usedSpaceInMB ve freeSpaceInMB değerlerini bildirir.
• MediaCountInfoModel, photoCount, videoCount ve audioCount değerlerini bildirir.
• Kullanıcı arayüzünüz ayrı değerlere gereksinim duyuyorsa description ayrıştırmak yerine model özelliklerini kullanın.