Table of Contents for SDK updates

2.0.1 SDK changes
  • Resolves an under retain in the xpc.
  • Resolves an issue where the xpc will remain running when not needed, resolves #563
  • Resolves an over retain in the framework.
  • Should make startup of applications slightly faster, by resolving 83 (usage of bundleWithIdentifier is now gone).
  • Increases the reliability of translating dictionaries into xml plists, thanks to a patch from Thaddeus.
2.0 SDK changes

1.3.1 SDK changes

1.3 SDK changes

Changes introduced in the 2.0 SDK

The 2.0 SDK provides feature enhancements and bug fixes. The major change is support for Notification Center

Changes in the 2.0 SDK are listed below:

Support for Notification Center

The Growl 2.0 SDK implements support for Notification Center. The idea here is that it should very simple for you to add in support for Notification Center by updating the Framework, and the XPC if you have implemented that. The SDK includes more information about this in the readme

Mist position controller works better.

The Mist positioning controller works much better in the 2.0 framework.

Notification description is now supported by GNTP baked into the framework

Notification descriptions were added back into the framework.

Changes introduced in the 1.3.1 SDK

The 1.3.1 SDK has a few changes to address issues reported with the 1.3 SDK. Please review these changes and the changes in the 1.3 SDK when updating to the newer frameworks.

Changes in the 1.3.1 SDK are listed below:

Introducing MultiGrowl

The 1.3.1 SDK introduces MultiGrowl. MultiGrowl provides a source based example of how to load different versions of the framework based on which OS X version your application is run. MultiGrowl will show you how to for example load the 1.2.3 framework on 10.5, and the 1.3 framework on 10.6. This page lists which versions of the framework are compatible which different OS X versions.

Mist now respects the default notifications list.

In the 1.3 framework, Mist would notify about all notifications in the list. Now Mist will only notify about the default notifications in the list. Notifications which are registered as disabled will not fire with Mist.

The GCDAsyncSocket class has been prefixed to avoid namespace collisions.

In the 1.3 framework, the GCDAsyncSocket class was not prefixed. The 1.3.1 framework addresses this issue. This resolves issue #344

Fixes an issue on machines where the hostname is not set.

In the 1.3 framework, if the hostname was not set then the framework would crash. The 1.3.1 framework addresses this issue.

Changes introduced in the 1.3 SDK

The 1.3 SDK has multiple different changes which are listed below:

Click to go to the section you want to learn about.

Sandboxing in Your Application

The Growl 1.3 Framework helps with sandboxing in 2 ways. First, we have added GNTP support for sending notifications to the local Growl application. However, you will most likely need to justify this to Apple, as they want everyone to justify entitlements in their applications. If you either don't need networking in your core app, or you have already separated out your core app's networking into an XPC to make that justification easier, then we recommend using the XPC based version of GNTP. The XPC version in the new framework is available to make it that much more secure, and it is easier to justify to the reviewers in the app store.

Growl.framework 1.3 still supports sending notes and receiving feedback from Growl 1.2.2. However, in a sandboxed environment, these will not be supported (this support is for running on 10.6 where sandboxing entitlements are ignored, and Growl.app 1.3 will not be available).

If you choose to use the XPC, com.company.application.GNTPClientService.xpc will need to be renamed, and signed by you, it will not need to be recompiled. We will supply one named com.growl.appname.GNTPClientService.xpc which will need to be changed to your app's bundle ID. We provide a script which provides an example of this, gntp-rename-move.rb. This script is what we use internally, so it assumes we are building the XPC everytime, but for your purposes you will only need the rename and resign portion once per version of the XPC.

Example script phase on the main build target (from BeepHammer) for adding the XPC to the bundle:

XPC_START="$BUILT_PRODUCTS_DIR"
XPC_SCRIPT="$SRCROOT/../../scripts/xpc-rename-move.rb"
ruby "$XPC_SCRIPT" "$XPC_START" "$BUILT_PRODUCTS_DIR/$WRAPPER_NAME"
"$CODE_SIGN_IDENTITY"

The first argument is where the original XPC bundle (com.company.application?) lives, second is where its headed to (your application), third argument is your code sign identity.

There is one new delegate method:

- (BOOL) hasNetworkClientEntitlement;

This method is required if you are sandboxed, and going to be using the network client entitlement on the main application instead of the XPC. We could not find a way to detect this well in a sandboxed environment so we are simply are going to ask you. All you have to do here if you are using the network client entitlement is implement this, and return YES, no need for any logic, if we are on 10.6 and sandboxing is ignored, we won't care about this, Growl.app 1.3+ is 10.7+ only, so GNTP is out as a choice anyways.

Introducing Mist

Over the years we have come to the conclusion; thanks in part to a large group of developers separately contacting us, installing Growl without telling end users, or by using the Growl-WithInstaller.framework; that we needed to provide a way to have notifications fire even when Growl is not installed. Growl 1.3 addresses this concern by introducing a fire and forget notification that we are calling Mist.

Mist was developed with the feedback of many developers from different types of applications. Our goal here is to provide the end user with a more cohesive experience. In the past this would have been to prompt the user to install Growl. Growl-WithInstaller.framework was great for the intended purpose, but some developers abused it, some developers had issues with when the installation prompt would come up, and it was a large framework to ship for an optional feature in most of the situations that we encountered. We want to provide a great experience to both end users and developers. Hence the motivation for Mist.

If the end user does not have Growl installed, is on 10.6 or 10.7, and your application has the Growl 1.3 framework, then Mist will fire a notification. This is an opt out solution, so if your application needs to only fire a notification if Growl is running, then you can opt out of Mist entirely.

If you are a developer with an application which already includes/implements Growl support through Growl.framework, then here are the steps to get Mist.

  1. Replace the framework in your application with Growl.framework from at least the Growl 1.3 SDK, or newer if available.
  2. Stop and remove Growl from your system to test Mist.

Note: If your application uses Growl-WithInstaller.framework, then you will need to take more steps in your application. Please contact our Development google group if you have any questions

If your application would benefit from preferences for end users if Growl is not present, it is our recommendation that you provide these.

One last note here. If you need to disable Mist. Say for instance you already have a checkbox for notifications, and you want to be able to toggle them on or off, you can do that. This is how:

[GrowlApplicationBridge setShouldUseBuiltInNotifications:NO];

You can also disable Mist globally if you need to test it, or just do not like it. The following is how to do that:

defaults write -g com.growl.growlframework.mist.enabled -bool YES or NO

We have a ticket on this in case you would like to further review how it works here.

Compatibility with newer versions of Growl

Growl.framework 1.3 is designed to work with both Growl 1.2.2 and older, and Growl 1.3 and higher. The framework will attempt to communicate in multiple ways with Growl to ensure that the notification which your application is sending gets to where it is going.

The SDK removes the Growl-WithInstaller framework.

The 1.3 SDK removes the Growl-WithInstaller.framework due to a number of usability and technical issues. Going forward we recommend instead using the Mist built-in fire and forget display that comes with Growl.framework version 1.3.

The SDK adds a 1.2.3 framework

The 1.3 SDK also includes an update to the 1.2.2 framework. The 1.3 framework does not have PPC or 10.5 support, so we have included this framework as well for those who still need support for 10.5 and PPC. We have versioned this the 1.2.3 framework. It only has 2 changes:

  • Resolves a problem reported by Daniel Jalkut of Red Sweater Software where the framework can crash an application. This happened very rarely, but we highly recommend updating immediately to resolve this issue.
  • The isInstalled method will always return YES, as mentioned in this section.

The 1.2.3 framework is included in the 1.3 SDK, under the Legacy directory

The isInstalled method is deprecated.

The 1.3 and 1.2.3 frameworks both will always return YES for the isInstalled method. This method is deprecated going forward. Please discontinue use of this method as soon as possible.

There are multiple reasons for this change:

  • isRunning is a reliable method to find out if Growl is actually running.

  • Sandboxing will not allow for your application to go looking through the file system without special exceptions granted by Apple. With regards to Sandboxing, there will be no reliable way to find out that Growl is installed.
  • isInstalled was never meant to be used as a check for whether or not you should send a growl notification; so that abuse of it has resulted in the method's deprecation.