You can obtain the source and example programs at https://github.com/audiogum/iossdk.
Initialise the SDK with client id and secret
public public init(clientId: String, clientSecret: String, deviceId: String)
public public init(clientId: String, clientSecret: String, deviceId: String, configuration: AudiogumConfiguration)
clientId client key issued by AudiogumclientSecret client secret issued by AudiogumdeviceId unique device identifierconfiguration optional configuration specifying SDK optionsInitialise the SDK with AccessToken
public public init(accessToken: AccessToken, deviceId: String)
public public init(accessToken: AccessToken, deviceId: String, configuration: AudiogumConfiguration)
accessToken AccessToken issued by Audiogum APIdeviceId unique device identifierconfiguration optional configuration specifying SDK optionsIP address lookup based upon client IP address. This product includes GeoLite2 data created by MaxMind, available from http://www.maxmind.com
Requires signin scope.
public func getIpMap() -> Promise<IpLookup>
Gets country-specific configuration including both service configuration such as which content services are supported, and custom configuration settings for the client.
Requires signin scope.
public func getAppConfig() -> Promise<AppConfig>
Allows upload of arbitrary user config key/value pairs to store settings.
Requires write_userprofile scope.
public func updateUserConfig(userConfig: UserConfig) -> Promise<UserConfig>
userConfig oem-specific user configAdd or update user config by key
Requires write_userprofile scope.
public func updateUserConfigByKey(key: String, userConfig: UserConfig) -> Promise<IpLookup>
key config keyvalue config valueDelete user config by key
Requires write_userprofile scope.
public func deleteUserConfigByKey(key: String) -> Promise<Void>
key key to deleteGets previously stored key/value pairs.
Requires read_userprofile scope.
public func getUserConfig() -> Promise<UserConfig>
Get user config by key
Requires read_userprofile scope.
public func getUserConfigByKey(key: String) -> Promise<UserConfig>
key config keyAllows upload of a Base64 encoded JPG or PNG image with maximum size 800px x 800px. Once in place, an imageuri property will be added to the user account.
Requires write_userprofile scope.
public func updateUserImage(image: UserImage) -> Promise<UserImage>
image image to addDelete user image
Requires write_userprofile scope.
public func deleteUserImage() -> Promise<Void>
Add or update user profile image
Requires write_userprofile scope.
public func updateUserProfileImage(profileId: String, image: UserImage) -> Promise<UserImage>
image image to addprofileId User Profile IDRemove user profile image
Requires write_userprofile scope.
public func deleteUserProfileImage(profileId: String) -> Promise<Void>
profileId User Profile IDNative client user email reset - sends a password reset email
public func resetUserPasswor(email: String) -> Promise<Void>
email email addressLogin a user and set their token
public func loginUser(email: String, password: String, scope: String = "all") -> Promise<Void>
email email addresspassword passwordscope scopeLogin an external (shadow account) user and set their token
public func loginExternalUser(externalUserId: String, countryCode: String? = nil, scope: String = "all") -> Promise<Void>
externalUserId external user idcountryCode country codescope scopeLogin a mobile user and set their token
public func loginMobileUser(mobileNumber: String, code: String, scope: String = "all") -> Promise<Void>
mobileNumber mobile numbercode verification codescope scopeLogs the user out of the API, clearing any cached data present.
public func logoutUser()`
Is user currently logged in?
public func isUserLoggedIn() -> Bool`
Get the url for the login page
public func getLoginUrl(scope: String?, service: String?, state: String?) -> Promise<URL>
scope scopeservice service to login tostate stateRegiser a new user. Assumes password been confirmed on client
public func createUser(firstName: String, lastName: String, email: String, password: String) -> Promise<AccessToken>
firstName first namelastName last nameemail email addresspassword passwordGet user account details by userid Gets the full account details.
Requires read_userprofile scope.
public func getUser() -> Promise<UserInfo>
If currentpassword or newpassword are passed both are required otherwise any non-password field can be submitted optionally. If email is included for update, this will not be updated immediately but a verification email will be sent. Once the verification link is clicked, the email will update.
Requires write_userprofile scope.
public func updateUser(userinfo: UserInfo) -> Promise<UserInfo>
userInfo user infoGet user profiles
Requires read_userprofile scope.
public func getUserProfiles() -> Promise<UserProfile>
Add or updates user profile
Requires write_userprofile scope.
public func updateUserProfile(updateProfile: UserProfile) -> Promise<UserProfile>
userProfile User ProfileUpdate user profile details
Requires write_userprofile scope.
public func updateUserProfileById(profileId: String, userProfile: UserProfile) -> Promise<UserProfile>
userProfile User ProfileprofileId User Profile IDGet user profile details
Requires read_userprofile scope.
public func getUserProfileById(profileId: String) -> Promise<UserProfile>
profileId User Profile IDDelete a user profile
Requires write_userprofile scope.
public func deleteUserProfileById(profileId: String) -> Promise<Void>
profileId User Profile IDNative client verification - verifies a user's mobile number
public func verifyUserMobile(mobileNumber: String, code: String) -> Promise<Void>
mobileNumber mobile numbercode verification codeNative client verification - sends a verification email
public func verifyUserEmail(email: String) -> Promise<Void>
email email addressCheck if an account exists Check if an account exists by email address
public func checkUserExists(email: String, validate: Bool) -> Promise<Void>
email The Email address to look upvalidate Flag to enable email address validationGet help and support content Requires signin scope.
public func getSupportDocumentation(String language) -> Promise<SupportDocumentation>
language Language code to look for; falls back to enSends support email
Requires signin scope.
public func sendSupportEmail(supportEmail: SupportEmail) -> Promise<Void>
supportEmail email to sendpublic func getUserServices() -> Promise<LinkedServiceList>
Gets a list of services the user has linked to their account.
Requires read_userprofile scope.
public func getUserService(serviceId: String) -> Promise<LinkedService>
Gets details of a specific content service linked to the user's account, if available.
Requires read_userprofile scope.
serviceId id of the service to fetch details ofGets an authorize URI to start a OAuth2 flow with the content service.
Requires write_userprofile scope.
public func startServiceAuthorization(serviceId: String) -> Promise<UserServiceAuthorizeDetails>
serviceId id of the content service.Obtain or refresh a service access token
Requires write_userprofile scope.
public func obtainServiceToken(serviceid: String, code: String?) -> Promise<UserServiceCredentials>
serviceId id of the content service.code optional OAuth2 authorization code from the service.Remove a service access token
Requires write_userprofile scope.
public func removeServiceToken(serviceid: String) -> Promise<Void>
serviceId id of the content service.Browse content services. Returns a list of items of type category; which can be explored with the ultimate goal of drilling down to items of types such as internetradio, audiobook or playlist. To explore a category, pass it's ref to this API in the parent parameter. Some services will return nested items within the category meaning no is required to explore further.
Requires search scope.
public func browseService(service: String, parent: String? = nil, startindex: Int? = nil, itemsperpage: Int? = nil, children: Int? = nil) -> Promise<SearchResultsGroup>
service The content serviceparent Optional parent group for drill downstartindex Optional paging - the offset that items should start at - defaults to 0itemsperpage Optional paging - the number of items to return in each bucket - defaults to 20children Optionally 'peek' into categories and include this number of child items in each category - defaults to 0 (no child item peeking), maximum 5Get an artist by id Get an artist by id. Returns artisttype, biogs, dateofbirth, dateofdeath, gender, genres, images, links, name, origin, originname, popularity, related, similar, services, tags, territory, yearsactive.
Requires search scope.
public func getArtist(artistId: String) -> Promise<Artist>
artistId Artist idGets an artist's albums or songs from a service based on our id Gets an artist's albums or songs from a service based on our id
Requires search scope.
public func getArtistSongs(artistId: String, service: String) -> Promise<TrackListing>
artistId Audiogum artist idservice The content serviceGets an artist's albums or songs from a service based on our id Gets an artist's albums or songs from a service based on our id
Requires search scope.
public func getArtistSongs(artistId: String, service: String, startindex: Int? = nil) -> Promise<TrackListing>
artistId Audiogum artist idservice The content servicestartindex paging - the offset that items should start at - defaults to 0Gets an artist's songs from a service based on our id
Requires search scope.
public func getArtistSongs(artistId: String, service: String, startindex: Int? = nil, itemsperpage: Int? = nil) -> Promise<TrackListing>
artistId Audiogum artist idservice The content servicestartindex paging - the offset that items should start at - defaults to 0itemsperpage paging - the number of items to return - defaults to 50Gets an artist's songs from a service based on the service ref
Requires search scope.
public func getArtistSongsByRef(ref: String, service: String, startindex: Int? = nil, itemsperpage: Int? = nil) -> Promise<TrackListing>
ref service ref for this artistservice The content servicestartindex paging - the offset that items should start at - defaults to 0itemsperpage paging - the number of items to return - defaults to 50Gets an artist's albums from a service based on our id
Requires search scope.
public func getArtistAlbums(artistId: String, service: String, startindex: Int? = nil,itemsperpage: Int? = nil) -> Promise<PlaylistListing>
artistId Audiogum artist idservice The content servicestartindex paging - the offset that items should start at - defaults to 0itemsperpage paging - the number of items to return - defaults to 50Gets an artist's albums from a service based on the service ref
Requires search scope.
public func getArtistAlbumsByRef(ref: String, service: String, itemsperpage: Int? = nil, startindex: Int? = nil) -> Promise<PlaylistListing>
ref Service ref for this artistservice The content servicestartindex paging - the offset that items should start at - defaults to 0itemsperpage paging - the number of items to return - defaults to 50Gets an artist's items of a specific type from a service based on the service ref
Requires search scope.
public func getArtistItemsByRef(ref: String, service: String, itemtype: String, itemsperpage: Int? = nil, startindex: Int? = nil) -> Promise<SearchResultsGroup>
ref Service ref for this artistservice The content serviceitemtype The type of item to fetch. See AppConfig.Service.drilldowntypes in getAppConfig response for valid types for each service.startindex paging - the offset that items should start at - defaults to 0itemsperpage paging - the number of items to return - defaults to 50Search across content services. Returns search results in various buckets
Requires search scope.
public func search(term: String? = nil, itemsperpage: Int? = nil, types: [String]? = nil, services: [String]? = nil) -> Promise<SearchResults>
term Content queryitemsperpage Number of items in each bucket - default 3types Optional filter parameter that limits types searched to those that are in this arrayservices Optional filter parameter that limits the services searched to those that are in this list (assuming they are allowed for the user)Get tracks for an album
Requires search scope.
public func getAlbumTracks(service: String,ref: String,startindex: Int? = nil,itemsperpage: Int? = nil) -> Promise<TrackListing>
service The content serviceref Service reference of parentstartindex Optional paging - the offset that items should start at - defaults to 0itemsperpage Optional paging - the number of items to return - defaults to 50Get tracks for a playlist
Requires search scope.
public func getPlaylistTracks(service: String, ref: String, startindex: Int? = nil, itemsperpage: Int? = nil) -> Promise<TrackListing>
service The content serviceref Service reference of parentstartindex Optional paging - the offset that items should start at - defaults to 0itemsperpage Optional paging - the number of items to return - defaults to 50Gets songs of a parent item - e.g. songs for an album, playlist. See https://www.audiogum.com/developers/docs/contentaggregation#drill_down.
Requires search scope.
public func getSongsByParent(type: String, ref: String, service: String, itemsperpage: Int? = nil, startindex: Int? = nil) -> Promise<TrackListing>
type The resource typeservice The content serviceref The content service resource referencestartindex Optional paging - the offset that items should start at - defaults to 0itemsperpage Optional paging - the number of items to return - defaults to 50Gets a song by service reference.
Requires search scope.
public func getServiceSong(ref: String, service: String, itemsperpage: Int? = nil, startindex: Int? = nil) -> Promise<Track>
ref The content service resource referenceservice The content servicestartindex Optional paging - the offset that items should start at - defaults to 0itemsperpage Optional paging - the number of items to return - defaults to 50Gets a playlist or album by service reference.
Requires search scope.
public func getServicePlaylist(type: String, ref: String, service: String, itemsperpage: Int? = nil, startindex: Int? = nil) -> Promise<Playlist>
type The resource type ("playlist" or "album")ref The content service resource referenceservice The content servicestartindex Optional paging - the offset that items should start at - defaults to 0itemsperpage Optional paging - the number of items to return - defaults to 50Search artists
Requires search scope.
public func searchArtist(term: String, itemsperpage: Int? = nil, startindex: Int? = nil, service: String? = nil) -> Promise<SearchResultsGroup>
term Query to search foritemsperpage Number of items in each bucket - default 20startindex Page start position - default 0service Service to searchSearch artists
Requires search scope.
public func searchArtistByIds(ids: [String], itemsperpage: Int? = nil, service: String? = nil) -> Promise<SearchResultsGroup>
id IDs to obtain details foritemsperpage Number of items in each bucket - default 20service Service to searchSingle bucket results for paging Drill down into detailed results for paging through a bucket.
Requires search scope.
public func searchByTypeService(type: String, service: String, term: String, itemsperpage: Int? = nil, startindex: Int? = nil) -> Promise<SearchResultsGroup>
type The bucket typeservice The content serviceterm Content queryitemsperpage Number of items in each bucket - default 20startindex Page start position - default 0Get a list of genres. Includes popularity in the current country and localized name.
Requires search scope.
public func getGenres(itemsperpage: Int? = nil, startindex: Int? = nil) -> Promise<Genres>
startindex Paging - the offset that items should start atitemsperpage Paging - the number of items to returnGet the top artists (by popularity) for a selection of given genres
Requires search scope.
public func getTopArtistsForGenre(genres: [String], fields: [String]? = nils, itemsperpage: Int? = nil, startindex: Int? = nil) -> Promise<TopArtistsByGenre>
genre The genres to get topartists forstartindex Paging - the offset that items should start atitemsperpage Paging - the number of items to returnfields The fields to returnThe most popular artists across a range of genres, merged together.
Requires search scope.
public func getTopArtists(fields: [String]? = nils, itemsperpage: Int? = nil) -> Promise<TopArtists>
itemsperpage Paging - the number of items to returnfields The fields to returnRequest to create a playable and associate it with a device, based on specified parameters. This will update an existing playable if it exists for the same user with the same parameters. For examples, see https://www.audiogum.com/partners/docs/playback.html.
Requires write_playlists scope.
public func createPlayable(playableRequest: CreatePlayableRequest) -> Promise<Playable>
playableRequest Information required to create a user playableGet information for a playable for playback based on its id. Depending on the type of playable, this gives a list of items or a streamurl for playback, plus data for service authentication where necessary. For examples, see https://www.audiogum.com/partners/docs/playback.html
Requires read_playlists scope.
public func getPlayableTracks(playableId: String, itemsperpage: Int? = nil, startindex: Int? = nil, streamUrls: Bool? = true) -> Promise<PlayableTracks>`
playableId id of playablestartindex the offset that items should start at - defaults to 0itemsperpage Optional paging - the number of items to return - defaults to 50streamUrls Optionally omit stream urls (false). Default (true) indicates include where applicableDeletes a specific playable based on its id
Requires write_playlists scope.
public func deletePlayable(playableId: String) -> Promise<Void>
playableId id of playableGet the basic details of a specific playable based on its id (note: this is not for playback purposes)
Requires write_playlists scope.
public func getUserPlayable(playableId: String) -> Promise<Playable>
playableId id of playableList the playables created by the user. By default this gives results in order of most recently used.
Requires read_playlists scope.
public func getUserPlayables(type: String? = nil, service: String? = nil, deviceId: String? = nil, itemsperpage: Int? = nil, startindex: Int? = nil) -> Promise<Playables>
type Optionally filter by type of playableservice Optionally filter by service providerdeviceId Optionally filter by devicestartindex Start index for paging (default 0)itemsperpage Number of results per page (default 10)Get the details including items of a specific playable based on its id (note: this is not for playback purposes)
Requires read_playlists scope.
public func getUserPlayableItems(playableId: String, itemsperpage: Int?, startindex: Int?) -> Promise<PlayableTracks>
playableId id of playablestartindex the offset that items should start at - defaults to 0itemsperpage optional paging - the number of items to return - defaults to 50Refresh streaming urls on behalf of the user for specific items from a service, for the case of time-limited content
Requires write_playlists scope.
public func refreshStreamUrls(playableId: String, service: String, trackIds: [String]) -> Promise<TrackListing>
playableId id of playableservice servicetrackIds track ids to refreshpublic func authenticateForVoice() -> Promise<Void>
Authenticates the user, creating a 'speech' scoped token and a token valid for use in the remote control websockets API. If not called separately, this will be done the first time the openVoiceSession() function is used.
Call this method early in your flow if you know you will need voice capabilities, as opening the first voice session without first calling this method can be slow and lead to a poor user experience.
See https://www.audiogum.com/developers/docs/naturallanguageunderstanding.html for more details.
Starts a voice session. This allows the client to talk to the Audiogum Voice service which are APIs for controlling devices through voice commands. This method must be called before any data is sent to the voice service through sendVoiceMessage(message: String!) or sendVoiceMessage(message: String!).
See https://www.audiogum.com/developers/docs/naturallanguageunderstanding.html for more details.
public func openVoiceSession(voiceProperties: VoiceProperties, delegate: VoiceDelegate) -> Promise<Void>
voiceProperties The voiceproperties message must be sent by the device on the Remote Control WebSocket to initiate a voice interaction.delegate An object that will respond to messages sent back from the voice service. It may also be sent again during the interaction as necessary to update nowplaying data if the player state changes.Sends a voice terminator
public func sendVoiceTerminator() throws
Send a string message to the voice service.
See https://www.audiogum.com/developers/docs/naturallanguageunderstanding.html for more details.
public func sendVoiceMessage(message: String!) throws
message Message to be sent to voice serviceSend a message as data to the voice service.
See https://www.audiogum.com/developers/docs/naturallanguageunderstanding.html for more details.
public func sendVoiceMessage(data: NSData) throws
message Data to be sent to voice serviceCloses the active voice session, if any is currently connected.
See https://www.audiogum.com/developers/docs/naturallanguageunderstanding for more details.
public func closeVoiceSession() throws
public func generateResponseAudio(phraseKey: String, languageCode: String? = nil) -> Promise<RemoteControlCommand.Respond>
Generates an audio response for the specified phrase in the language desired.
Requires speech scope
phraseKey the key of the phrase to generate audio for.languageCode the language to use when generating. If not specified, the user's language will be used.public func getSpeechSuggestions(nowPlaying: SpeechNowPlaying?) -> Promise<SpeechSuggestionResponse>
Retrieves examples of speech requests that the user can make to the Audiogum service.
Requires speech scope
nowPlaying optionally supply the current playing information for more personalised speech examples.public func makeSpeechRequestWithActionText(request: TextToActionRequest) -> Promise<TextToActionResponse>
Convert the text of an instruction into the action that should be performed.
Requires speech scope
request information about the request to be made.Get remotecontrol details of connected remote control device
See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.
public func getRemoteControlDetails(remoteControlToken: String) -> Promise<RemoteControlSupportedActionsDetails>
remoteControlToken Remote control tokenSend a command to a remote control device
See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.
public func sendRemoteControlCommand(command: RemoteControlCommand) -> Promise<Void>
command Remote control commandPromise of Void
Get player state from a connected remote control device
See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.
public func getRemoteControlDevicePlayerDetails(remoteControlToken: String) -> Promise<DevicePlayerDetails>
remoteControlToken Remote control tokenGet device state from a connected remote control device
See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.
public func getRemoteControlDeviceDetails(remoteControlToken: String) -> Promise<RemoteControlDeviceDetails>
remoteControlToken Remote control tokenGet preset state from a connected remote control device
See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.
public func getRemoteControlDevicePresetDetails(remoteControlToken: String)-> Promise<RemoteControlDevicePresetDetails>
remoteControlToken Remote control tokenpublic func getTasteProfile() -> Promise<TasteProfile>
Gets the taste profile
public func addToTasteProfile(itemsToAdd: TasteProfile) -> Promise<Void>
Add items to the taste profile.
itemsToAdd items to add to the taste profilepublic func addLikesToTasteProfile(artists: [Artist]? = nil, internetradios: [InternetRadio]? = nil, playlists: [Playlist]? = nil, albums: [Playlist]? = nil, songs: [Track]? = nil) -> Promise<Void>
Add likes to the taste profile.
artists artists to addinternetradios internetradios to addplaylists playlists to addalbums albums to addsongs songs to addpublic func deleteFromTasteProfile(itemsToDelete: TasteProfile) -> Promise<Void>
Removes multiple items from the taste profile.
itemsToDelete items to delete from the taste profilepublic func deleteLikesFromTasteProfile(artists: [Artist]? = nil, internetradios: [InternetRadio]? = nil, playlists: [Playlist]? = nil, albums: [Playlist]? = nil, songs: [Track]? = nil) -> Promise<Void>
Removes likes from the taste profile.
artists artists to removeinternetradios internetradios to removeplaylists playlists to removealbums albums to removesongs songs to removegetTasteGenreTags(tagsPerItem: Int = 1) -> Promise<TagsProfile>
Gets the top genre tags matching user's profile.
tagsPerItem optionally limit the tag values used per item to the specified number of most important valuesaddToTasteProfileByName(itemsToAdd: TasteProfile) -> Promise<Void>
Add items to the taste profile by name.
itemsToAdd the items to add by namecheckArtistTasteStateByName(name: String) -> Promise<TasteMatch>
Check state of artists in taste profile by name.
name the name to attempt to matchpublic func sendAnalyticsEvents(_ events: [Event], validateOnly: Bool?) -> Promise<Void>`
Sends analytics events, recording user or client actions or behaviour.
Requires write_events scope.
See https://www.audiogum.com/developers/docs/analytics.html for more details.
events the collection of events to send.validateOnly if true, the events will validated but not recorded.public func uploadLog(deviceId: String, logType: String, content: String) -> Promise<Void>
Upload a log or crash dump file.
Requires write_device scope.
deviceId The id of the device the log relates to.logType The type of log to be sent.content The content to be logged.public func getAppRelease(region: String, platform: String, appstore: String, version: String,
language: String?, altapp: String?, platformversion: String?, devicemanufacturer: String?,
devicename: String?) -> Promise<AppRelease>
Fetches details of any available app update.
region Region to check for (required)platform Operating system (required)appstore App Store to check (required)version Current version installed (required)language Get releasenotes in this languagealtapp Codename of alternative app. Omit this for releases of the default app.platformversion Optional operating system versiondevicemanufacturer Optional device manufacturerdevicename Optional device namepublic func registerDevice() -> Promise<Void>
Registers the device making the SDK calls with the Audiogum API. This is required to ensure your analytics data is as accurate as possible.
public func getUserDevices(ofType: [String]?) -> Promise<DeviceList>
Lists the devices this user has been associated with.
ofType An optional array of device types to fetch.public func getUserOwnedDevices() -> Promise<DeviceList>
Lists the devices currently owned by the current user. Note that the full device info is not shown here.
public func registerUserOwnedDevice(deviceid: String) -> Promise<Void>
Creates an ownership relationship betweenn the specified device and the current user. If the device already has a different owner, this request will fail with 409 response code.
deviceid the id of the device being marked as owned.