SUAppcastItem

Objective-C

@interface SUAppcastItem : NSObject <NSSecureCoding>

Swift

class SUAppcastItem : NSObject, NSSecureCoding

The appcast item describing an update in the application’s appcast feed.

An appcast item represents a single update item in the SUAppcast contained within the <item> element.

Every appcast item must have a versionString, and either a fileURL or an infoURL. All the remaining properties describing an update to the application are optional.

Extended documentation and examples on using appcast item features are available at: https://sparkle-project.org/documentation/publishing/

  • The version of the update item.

    Sparkle uses this property to compare update items and determine the best available update item in the SUAppcast.

    This corresponds to the application update’s CFBundleVersion

    This is extracted from the <sparkle:version> element, or the sparkle:version attribute from the <enclosure> element.

    Declaration

    Objective-C

    @property (copy, readonly) NSString *_Nonnull versionString;

    Swift

    var versionString: String { get }
  • The human-readable display version of the update item if provided.

    This is the version string shown to the user when they are notified of a new update.

    This corresponds to the application update’s CFBundleShortVersionString

    This is extracted from the <sparkle:shortVersionString> element, or the sparkle:shortVersionString attribute from the <enclosure> element.

    Declaration

    Objective-C

    @property (copy, readonly, nullable) NSString *displayVersionString;

    Swift

    var displayVersionString: String? { get }
  • The file URL to the update item if provided.

    This download contains the actual update Sparkle will attempt to install. In cases where a download cannot be provided, an infoURL must be provided instead.

    A file URL should have an accompanying contentLength provided.

    This is extracted from the url attribute in the <enclosure> element.

    Declaration

    Objective-C

    @property (readonly, nullable) NSURL *fileURL;

    Swift

    var fileURL: URL? { get }
  • The content length of the download in bytes.

    This property is used as a fallback when the server doesn’t report the content length of the download. In that case, it is used to report progress of the downloading update to the user.

    A warning is outputted if this property is not equal the server’s expected content length (if provided).

    This is extracted from the length attribute in the <enclosure> element. It should be specified if a fileURL is provided.

    Declaration

    Objective-C

    @property (nonatomic, readonly) uint64_t contentLength;

    Swift

    var contentLength: UInt64 { get }
  • The info URL to the update item if provided.

    This informational link is used to direct the user to learn more about an update they cannot download/install directly from within the application. The link should point to the product’s web page.

    The informational link will be used if informationOnlyUpdate is YES

    This is extracted from the <link> element.

    Declaration

    Objective-C

    @property (readonly, nullable) NSURL *infoURL;

    Swift

    var infoURL: URL? { get }
  • Indicates whether or not the update item is only informational and has no download.

    If infoURL is not present, this is NO

    If fileURL is not present, this is YES

    Otherwise this is determined based on the contents extracted from the <sparkle:informationalUpdate> element.

    Declaration

    Objective-C

    @property (readonly, getter=isInformationOnlyUpdate) BOOL informationOnlyUpdate;

    Swift

    var isInformationOnlyUpdate: Bool { get }
  • The title of the appcast item if provided.

    This is extracted from the <title> element.

    Declaration

    Objective-C

    @property (copy, readonly, nullable) NSString *title;

    Swift

    var title: String? { get }
  • The date string of the appcast item if provided.

    The date property is constructed from this property and expects this string to comply with the following date format: E, dd MMM yyyy HH:mm:ss Z

    This is extracted from the <pubDate> element.

    Declaration

    Objective-C

    @property (copy, readonly, nullable) NSString *dateString;

    Swift

    var dateString: String? { get }
  • The date constructed from the dateString property if provided.

    Sparkle by itself only uses this property for phased group rollouts specified via phasedRolloutInterval, but clients may query this property too.

    This date is constructed using the en_US locale.

    Declaration

    Objective-C

    @property (copy, readonly, nullable) NSDate *date;

    Swift

    var date: Date? { get }
  • The release notes URL of the appcast item if provided.

    This external link points to an HTML file that Sparkle downloads and renders to show the user a new or old update item’s changelog.

    An alternative to using an external release notes link is providing an embedded itemDescription.

    This is extracted from the <sparkle:releaseNotesLink> element.

    Declaration

    Objective-C

    @property (readonly, nullable) NSURL *releaseNotesURL;

    Swift

    var releaseNotesURL: URL? { get }
  • The description of the appcast item if provided.

    A description may be provided for inline/embedded release notes for new updates using <![CDATA[...]]> This is an alternative to providing a releaseNotesURL.

    This is extracted from the <description> element.

    Declaration

    Objective-C

    @property (copy, readonly, nullable) NSString *itemDescription;

    Swift

    var itemDescription: String? { get }
  • The required minimum system operating version string for this update if provided.

    This version string should contain three period-separated components.

    Example: 10.12.0

    Use minimumOperatingSystemVersionIsOK property to test if the current running system passes this requirement.

    This is extracted from the <sparkle:minimumSystemVersion> element.

    Declaration

    Objective-C

    @property (copy, readonly, nullable) NSString *minimumSystemVersion;

    Swift

    var minimumSystemVersion: String? { get }
  • Indicates whether or not the current running system passes the minimumSystemVersion requirement.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL minimumOperatingSystemVersionIsOK;

    Swift

    var minimumOperatingSystemVersionIsOK: Bool { get }
  • The required maximum system operating version string for this update if provided.

    A maximum system operating version requirement should only be made in unusual scenarios.

    This version string should contain three period-separated components.

    Example: 10.13.0

    Use maximumOperatingSystemVersionIsOK property to test if the current running system passes this requirement.

    This is extracted from the <sparkle:maximumSystemVersion> element.

    Declaration

    Objective-C

    @property (copy, readonly, nullable) NSString *maximumSystemVersion;

    Swift

    var maximumSystemVersion: String? { get }
  • Indicates whether or not the current running system passes the maximumSystemVersion requirement.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL maximumOperatingSystemVersionIsOK;

    Swift

    var maximumOperatingSystemVersionIsOK: Bool { get }
  • The channel the update item is on if provided.

    An update item may specify a custom channel name (such as beta) that can only be found by updaters that filter for that channel. If no channel is provided, the update item is assumed to be on the default channel.

    This is extracted from the <sparkle:channel> element. Old applications must be using Sparkle 2 or later to interpret the channel element and to ignore unmatched channels.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSString *channel;

    Swift

    var channel: String? { get }
  • The installation type of the update at fileURL

    This may be:

    • application - indicates this is a regular application update.
    • package - indicates this is a guided package installer update.
    • interactive-package - indicates this is an interactive package installer update (deprecated; use “package” instead)

    This is extracted from the sparkle:installationType attribute in the <enclosure> element.

    If no installation type is provided in the enclosure, the installation type is inferred from the fileURL file extension instead.

    If the file extension is pkg or mpkg, the installation type is package otherwise it is application

    Hence, the installation type in the enclosure element only needs to be specified for package based updates distributed inside of a zip or other archive format.

    Old applications must be using Sparkle 1.26 or later to support downloading bare package updates (pkg or mpkg) that are not additionally archived inside of a zip or other archive format.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSString *_Nonnull installationType;

    Swift

    var installationType: String { get }
  • The phased rollout interval of the update item in seconds if provided.

    This is the interval between when different groups of users are notified of a new update.

    For this property to be used by Sparkle, the published date on the update item must be present as well.

    After each interval after the update item’s date, a new group of users become eligible for being notified of the new update.

    This is extracted from the <sparkle:phasedRolloutInterval> element.

    Old applications must be using Sparkle 1.25 or later to support phased rollout intervals, otherwise they may assume updates are immediately available.

    Declaration

    Objective-C

    @property (copy, readonly, nullable) NSNumber *phasedRolloutInterval;

    Swift

    @NSCopying var phasedRolloutInterval: NSNumber? { get }
  • The minimum bundle version string this update requires for automatically downloading and installing updates if provided.

    If an application’s bundle version meets this version requirement, it can install the new update item in the background automatically.

    Otherwise if the requirement is not met, the user is always prompted to install the update. In this case, the update is assumed to be a majorUpgrade.

    If the update is a majorUpgrade and the update is skipped by the user, other future update alerts with the same minimumAutoupdateVersion will also be skipped.

    This version string corresponds to the application’s CFBundleVersion

    Declaration

    Objective-C

    @property (copy, readonly, nullable) NSString *minimumAutoupdateVersion;

    Swift

    var minimumAutoupdateVersion: String? { get }
  • Indicates whether or not the update item is a major upgrade.

    An update is a major upgrade if the application’s bundle version doesn’t meet the minimumAutoupdateVersion requirement.

    Declaration

    Objective-C

    @property (readonly, getter=isMajorUpgrade) BOOL majorUpgrade;

    Swift

    var isMajorUpgrade: Bool { get }
  • Indicates whether or not the update item is critical.

    Critical updates are shown to the user more promptly. Sparkle’s standard user interface also does not allow them to be skipped.

    This is determined and extracted from a top-level <sparkle:criticalUpdate> element or a sparkle:criticalUpdate element inside of a sparkle:tags element.

    Old applications must be using Sparkle 2 or later to support the top-level <sparkle:criticalUpdate> element.

    Declaration

    Objective-C

    @property (readonly, getter=isCriticalUpdate) BOOL criticalUpdate;

    Swift

    var isCriticalUpdate: Bool { get }
  • Specifies the operating system the download update is available for if provided.

    If this property is not provided, then the supported operating system is assumed to be macOS.

    Known potential values for this string are macos and windows

    Sparkle on Mac ignores update items that are for other operating systems. This is only useful for sharing appcasts between Sparkle on Mac and Sparkle on other operating systems.

    Use macOsUpdate property to test if this update item is for macOS.

    This is extracted from the sparkle:os attribute in the <enclosure> element.

    Declaration

    Objective-C

    @property (copy, readonly, nullable) NSString *osString;

    Swift

    var osString: String? { get }
  • Indicates whether or not this update item is for macOS.

    This is determined from the osString property.

    Declaration

    Objective-C

    @property (readonly, getter=isMacOsUpdate) BOOL macOsUpdate;

    Swift

    var isMacOsUpdate: Bool { get }
  • The delta updates for this update item.

    Sparkle uses these to download and apply a smaller update based on the version the user is updating from.

    The key is based on the sparkle:version of the update. The value is an update item that will have deltaUpdate be YES

    Clients typically should not need to examine the contents of the delta updates.

    This is extracted from the <sparkle:deltas> element.

    Declaration

    Objective-C

    @property (copy, readonly, nullable) NSDictionary<NSString *, SUAppcastItem *> *deltaUpdates;

    Swift

    var deltaUpdates: [String : SUAppcastItem]? { get }
  • Indicates whether or not the update item is a delta update.

    An update item is a delta update if it is in the deltaUpdates of another update item.

    Declaration

    Objective-C

    @property (readonly, getter=isDeltaUpdate) BOOL deltaUpdate;

    Swift

    var isDeltaUpdate: Bool { get }
  • The dictionary representing the entire appcast item.

    This is useful for querying custom extensions or elements from the appcast item.

    Declaration

    Objective-C

    @property (copy, readonly) NSDictionary *_Nonnull propertiesDictionary;

    Swift

    var propertiesDictionary: [AnyHashable : Any] { get }
  • Unavailable

    Undocumented

    Declaration

    Objective-C

    - (instancetype)init NS_UNAVAILABLE;
  • An empty appcast item.

    This may be used as a potential return value in -[SPUUpdaterDelegate bestValidUpdateInAppcast:forUpdater:]

    Declaration

    Objective-C

    + (nonnull instancetype)emptyAppcastItem;

    Swift

    class func empty() -> Self
  • Deprecated

    Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.

    Undocumented

    Declaration

    Objective-C

    - (nullable instancetype)initWithDictionary:(NSDictionary *)dict __deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");

    Swift

    init?(dictionary dict: [AnyHashable : Any])
  • Deprecated

    Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.

    Undocumented

    Declaration

    Objective-C

    - (nullable instancetype)initWithDictionary:(NSDictionary *)dict failureReason:(NSString * _Nullable __autoreleasing *_Nullable)error __deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");

    Swift

    init?(dictionary dict: [AnyHashable : Any], failureReason error: AutoreleasingUnsafeMutablePointer<NSString?>?)
  • Deprecated

    Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.

    Undocumented

    Declaration

    Objective-C

    - (nullable instancetype)initWithDictionary:(NSDictionary *)dict relativeToURL:(NSURL * _Nullable)appcastURL failureReason:(NSString * _Nullable __autoreleasing *_Nullable)error __deprecated_msg("Properties that depend on the system or application version are not supported when used with this initializer. The designated initializer is available in SUAppcastItem+Private.h. Please first explore other APIs or contact us to describe your use case.");

    Swift

    init?(dictionary dict: [AnyHashable : Any], relativeTo appcastURL: URL?, failureReason error: AutoreleasingUnsafeMutablePointer<NSString?>?)