The Configuration File (.knsrc)

For this to work, a file that sets up KNewStuff khotnewstuff_example.knsrc is needed. The file has to be in kde/share/config/khotnewstuff_example.knsrc. (The name of the file is taken from the about data).

always: assume all downloaded files are archives and need to be extracted

never: never try to extract the file

archive: if the file is an archive, uncompress it, otherwise just pass it on

You have different options to set the target install directory:

StandardResource: standard ressouce dir, such as .kde/share/wallpapers. This is what KStandardDirs::locateLocal(name) will return.

TargetDir: a directory in the share/apps section, such as .kde/share/apps/wallpapers. This is what KStandardDirs::locateLocal("data", name) will return.

Downloaded HTML:

A new option has been added for KDE 4.5.
By default KNewStuff will ask if the user wants to open downloaded HTML files with a browser instead of trying to install them. This is so since most of the time HTML means a broken link or a link to a page from which the item can be downloaded. If you want to accept html (because your app actually uses KNewStuff to get html files, you should explicitly allow this:
AcceptHtmlDownloads=true

ProvidersUrl
The data has to come from somewhere, right? Up until KDE SC 4.5 you must specify ProvidersUrl with an url to the providers.xml file.
Starting with KDE 4.5 this is optional, and if you just want to use what KDE provides as default (http://download.kde.org/ocs/providers.xml, currently openDesktop.org), leave this out. The advantage of not specifying this field is that users can add more providers using the attica kcm (kcmshell4 kcm_attica).
Only if you have to (because you need a different provider) use:
ProvidersUrl=http://download.kde.org/ocs/providers.xml

Linking in CMakeLists.txt

To link against KNS3, just link against ${KDE4_KNEWSTUFF3_LIBS}. Example:

Using a Widget instead of the Dialog

If you don't like to use an external dialog, you can also use a widget instead. Just replace DownloadDialog with DownloadWidget and you're good to go. This is especially nice as additional page in existing config dialogs.