Kurallar ve Yapılandırma

İpuçlarının ne zaman görüntüleneceğini kontrol eden kurallar, parametreler, olaylar ve uygulama düzeyinde yapılandırma seçenekleri.

---

Rule

Yapı | TipKit

*iOS 17.0+, iPadOS 17.0+, Mac Catalyst 17.0+, macOS 14.0+, tvOS 17.0+, visionOS 1.0+, watchOS 10.0+*

İpucu görüntülemeden önce karşılanması gereken koşul.

struct Rule

Kurallar, ipuçlarınızın ne zaman görüntüleneceğini kontrol etmek için kullanılır. İki tür kural mevcuttur: parametre tabanlı ve olay tabanlı.

Parametre Tabanlı Kurallar

Uygulama durumunu izler. Örneğin, kullanıcı giriş yaptığında bir ipucu göstermek için:

1. İzlemek istediğiniz uygulama durumunu @Parameter makrosuyla tanımlayın. 2. #Rule makrosuyla bu duruma dayalı bir kural oluşturun. 3. Kural closure'ında görüntülenme koşullarını belirleyin.

struct FavoriteLandmarkTip: Tip {
    @Parameter
    static var userIsLoggedIn: Bool = false

    var rules: [Rule] {
        #Rule(Self.$userIsLoggedIn) {
            $0 == true
        }
    }
}

Olay Tabanlı Kurallar

Kullanıcı etkileşimlerini izler. Örneğin, bir olay üç veya daha fazla kez gerçekleştiğinde ipucu göstermek için:

1. İzlemek istediğiniz etkileşimi benzersiz id ile bir Event olarak tanımlayın. 2. #Rule makrosuyla bu etkileşime dayalı bir kural oluşturun. 3. Kural closure'ında görüntülenme koşullarını belirleyin.

struct FavoriteLandmarkTip: Tip {
    static let didViewLandmark: Event = Event(id: "didViewLandmark")

    var rules: [Rule] {
        #Rule(Self.didViewLandmark) {
            $0.donations.count > 3
        }
    }
}

Bileşik İşlemler (iOS 26+)

Tips.Rule.CompoundOperation numaralandırması ile kurallar arasında mantıksal işlemler belirlenebilir:

| İşlem | Açıklama | | --- | --- | | .conjunction | Mantıksal VE (and) kuralları | | .disjunction | Mantıksal VEYA (or) kuralları |

---

Parameter

Yapı | TipKit

*iOS 17.0+, iPadOS 17.0+, Mac Catalyst 17.0+, macOS 14.0+, tvOS 17.0+, visionOS 1.0+, watchOS 10.0+*

Sarmaladığı değerin durumunu izleyerek, değer değiştiğinde bağımlı ipucu kurallarını yeniden değerlendiren tip.

struct Parameter<Value> where Value : Decodable, Value : Encodable, Value : Sendable

Uyumlu bir tipi @Parameter makrosuyla sarmalayarak parametre oluşturulur. Tanımlayıcı (id), parametrenin kapsayan örneğine ve sarmaladığı özelliğin adına göre otomatik oluşturulur.

Parametreler, configure(_:)) çağrılmadan önce güncellenmez.

struct LandmarksUser {
    @Parameter
    static var hasFavoritedLandmark: Bool = false
}

struct FavoriteLandmarkTip: Tip {
    var rules: [Rule] {
        #Rule(LandmarksUser.$hasFavoritedLandmark) {
            $0 == false
        }
    }
}

Parametre Seçenekleri

ParameterOption.transient — Uygulama başlatmaları arasında parametre değerini sıfırlayan seçenek.

struct LandmarksUser {
    @Parameter(.transient)
    static var lastViewedLandmark: Landmark? = nil
}

Uyum: Identifiable, Sendable

---

Event

Yapı | TipKit

*iOS 17.0+, iPadOS 17.0+, Mac Catalyst 17.0+, macOS 14.0+, tvOS 17.0+, visionOS 1.0+, watchOS 10.0+*

Tekrarlanabilir, kullanıcı tanımlı eylem.

struct Event<DonationInfo> where DonationInfo : Decodable, DonationInfo : Encodable, DonationInfo : Sendable

Uygulamanızda bir veya daha fazla kez gerçekleşebilecek bir eylemi izlemek istediğinizde olay kullanın. Eylem gerçekleştiğinde donate()) çağrısıyla olaya bağış yaparak olay sayısını bir artırın.

İlişkili Bağış Değeri Olmadan

struct LandmarkTips: App {
    static let landmarksAppDidOpen = Tips.Event(id: "landmarksAppDidOpen")

    var body: some Scene {
        WindowGroup {
            ContentView()
                .onAppear { Self.landmarksAppDidOpen.sendDonation() }
        }
    }
}

struct LandmarkFeatureTip: Tip {
    var rules: [Rule] {
        #Rule(LandmarkTips.landmarksAppDidOpen) {
            $0.donations.donatedWithin(.week).count >= 3
        }
    }
}

İlişkili Bağış Değeri İle

struct LandmarkDetail: View {
    static let didViewLandmarkDetail = Tips.Event<DidViewLandmark>(id: "didViewLandmarkDetail")

    struct DidViewLandmark: Codable, Sendable {
        let landmarkID: Int
        let landmarkName: String
    }

    var body: some View {
        ScrollView {
            MapView(coordinate: landmark.locationCoordinate)
        }
        .onAppear {
            Self.didViewLandmarkDetail.sendDonation(
                .init(landmarkID: landmark.id, landmarkName: landmark.name)
            )
        }
    }
}

struct LandmarkDetailTip: Tip {
    var rules: [Rule] {
        #Rule(LandmarkDetail.didViewLandmarkDetail) {
            $0.donations.filter({ $0.landmarkName != "Wilbere Bowl" }).count > 3
        }
    }
}

Başlatıcılar

// Bağış değeri olmadan
init(id: String) where DonationInfo == Tips.EmptyDonation
init(id: String, donationLimit: Tips.DonationLimit)
    where DonationInfo == Tips.EmptyDonation  // iOS 26+

// İlişkili bağış değeri ile
init(id: String)
init(id: String, donationLimit: Tips.DonationLimit)  // iOS 26+

Bağış Yöntemleri

| Yöntem | Açıklama | | --- | --- | | donate() | Bağış değeri olmadan asenkron bağış yapar | | donate(_:) | İlişkili bağış değeri ile asenkron bağış yapar | | sendDonation(_:) | Bağış değeri olmadan asenkron bağış gönderir | | sendDonation(_:_:) | İlişkili bağış değeri ile asenkron bağış gönderir | | deleteDonations() | Olayın mevcut bağışlarını siler (iOS 26+) |

Donation Yapısı

Her bağış bir date özelliği taşır ve @dynamicMemberLookup aracılığıyla ilişkili bağış değerinin özelliklerine doğrudan erişim sağlar.

@dynamicMemberLookup struct Donation

DonationTimeRange

Bağışları zaman aralığına göre filtreleme:

// Statik özellikler
.minute, .hour, .day, .week

// Yöntemler
.minutes(_:), .hours(_:), .days(_:), .weeks(_:)

DonationLimit (iOS 26+)

Olayın saklayacağı ve sorgulayacağı maksimum bağış sayısı ve yaşı:

init(maximumCount: Int, maximumAge: Tips.DonationTimeRange? = nil)

Uyum: Identifiable, Sendable

---

Yapılandırma Seçenekleri

configure(_:)

Tip Yöntemi | TipKit

Uygulamanızdaki tüm ipuçlarının kalıcı durumunu yükler ve yapılandırır.

static func configure(_ configuration: [Tips.ConfigurationOption] = []) throws

Uygulama başlatılması sırasında çağırın. Varsayılan olarak tüm ipuçları, varsayılan konuma immediate gösterim sıklığıyla kalıcı olarak saklanır.

@main
struct SampleApp: App {
    init() {
        do {
            try Tips.configure()
        }
        catch {
            print("TipKit başlatılırken hata: \(error.localizedDescription)")
        }
    }
}

Özel yapılandırma ile:

do {
    try Tips.configure([
        .datastoreLocation(.groupContainer(identifier: "MyGroupContainer")),
        .displayFrequency(.hourly),
        .cloudKitContainer(.automatic)
    ])
}
catch {
    print("TipKit başlatılırken hata: \(error.localizedDescription)")
}

ConfigurationOption

Yapılandırma dizisine eklenebilecek üç seçenek türü:

DisplayFrequency — Gösterim Sıklığı

Bir ipucu gösterildikten sonra başka bir ipucunun uygun hale gelmesi için gereken minimum süre.

.displayFrequency(_ frequency: Tips.ConfigurationOption.DisplayFrequency)

| Değer | Açıklama | | --- | --- | | .immediate | Sıklık sınırlaması yok (varsayılan) | | .hourly | Saatte en fazla bir ipucu | | .daily | Günde en fazla bir ipucu | | .weekly | Haftada en fazla bir ipucu | | .monthly | Ayda en fazla bir ipucu |

DatastoreLocation — Veri Deposu Konumu

İpuçları veri deposunun diskteki konumunu belirler.

.datastoreLocation(_ location: Tips.ConfigurationOption.DatastoreLocation)

| Değer | Açıklama | | --- | --- | | .applicationDefault | Varsayılan uygulama destek dizini | | .groupContainer(identifier:) | Paylaşılan grup konteynerı | | .url(_:) | Özel disk konumu |

let tipsLocation = URL.applicationSupportDirectory.appendingPathComponent("LandmarkTips")
try Tips.configure([
    .datastoreLocation(.url(tipsLocation))
])

CloudKitContainer — CloudKit Senkronizasyonu (iOS 18+)

İpuçlarını CloudKit ile senkronize etmek için konteyner belirler.

.cloudKitContainer(_ container: Tips.ConfigurationOption.CloudKitContainer)

| Değer | Açıklama | | --- | --- | | .automatic | Uygulamanın yetkilendirmelerindeki ".tips" sonekli ilk konteyneri veya birincil konteyneri kullanır | | .named(_:) | Belirtilen CloudKit konteynerini kullanır |

---

Davranış Seçenekleri

Her ipucu, options özelliği aracılığıyla bireysel davranış seçenekleri tanımlayabilir:

MaxDisplayCount

İpucu en fazla kaç kez görüntülendikten sonra otomatik geçersiz kılınacağını belirler.

struct MaxDisplayCount  // TipOption'a uyumlu

Varsayılan olarak ipuçlarında maksimum gösterim sayısı yoktur.

var options: [any Option] {
    MaxDisplayCount(3)  // 3 kez görüntülendikten sonra otomatik geçersiz kılınır
}

MaxDisplayDuration

*iOS 18.0+, macOS 15.0+*

İpucu en fazla ne kadar süre görüntülendikten sonra geçersiz kılınacağını belirler.

struct MaxDisplayDuration  // TipOption'a uyumlu

Bu kümülatif bir değerdir — ipucu 2 dakikalık maksimum süre belirler ve Pazartesi 1 dakika, Salı 1 dakika gösterilirse otomatik olarak geçersiz kılınır.

İpucu görünümleri, çok hızlı belirip kaybolmayı önlemek için MaxDisplayDuration tarafından otomatik geçersiz kılınabilmeden önce minimum 60 saniyelik gösterim süresine sahiptir.

var options: [any Option] {
    MaxDisplayDuration(300.0)  // 5 dakika sonra otomatik geçersiz kılınır
}

IgnoresDisplayFrequency

İpucunun önceden yapılandırılmış gösterim sıklığı aralığına uyup uymayacağını kontrol eder.

struct IgnoresDisplayFrequency  // TipOption'a uyumlu

Varsayılan değer false. true olarak ayarlandığında, ipucu displayFrequency kısıtlaması karşılanmasa bile görüntülenebilir.

var options: [any Option] {
    IgnoresDisplayFrequency(true)
}

Seçenekleri Birleştirme

struct FavoriteBackyardTip: Tip {
    var options: [any Option] {
        MaxDisplayCount(3)
        MaxDisplayDuration(300.0)
        IgnoresDisplayFrequency(true)
    }
}