iOS SDK

You can obtain the source and example programs at https://github.com/audiogum/iossdk.

class AGMClient

Methods

init

Initialise the SDK with client key and secret

-initWithClientId:(NSString *)clientid clientSecret:(NSString *)clientSecret deviceId:(NSString *)deviceId
-initWithClientId:(NSString *)clientid clientSecret:(NSString *)clientSecret deviceId:(NSString *)deviceId configuration:(AGMConfiguration)configuration

Parameters

  • clientId client key issued by Audiogum
  • clientSecret client secret issued by Audiogum
  • deviceId unique device identifier
  • configuration configuration options to be used in this instance (optional)

init

Initialise the SDK with AccessToken

-initWithAccessToken:(AGMAccessToken *)accessToken deviceId:(NSString *)deviceId
-initWithAccessToken:(AGMAccessToken *)accessToken deviceId:(NSString *)deviceId configuration:(AGMConfiguration *)configuration

Parameters

  • accessToken access token issued by Audiogum API
  • deviceId unique device identifier
  • configuration optional configuration specifying SDK options

IP Address Lookup

IP address lookup based upon client IP address. This product includes GeoLite2 data created by MaxMind, available from http://www.maxmind.com

Requires signin scope.

-(FBLPromise<AGMIpLookup *> *) getIpMap

Returns

  • FBLPromise of AGMIpLookup

Get Client Configuration

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.

-(FBLPromise<AGMAppConfig *> *) getAppConfig

Returns

  • FBLPromise of AGMAppConfig

Add User Config

Allows upload of arbitrary user config key/value pairs to store settings.

Requires write_userprofile scope.

-(FBLPromise<AGMUserConfig *> *) updateUserConfig:(AGMUserConfig *)userConfig

Parameters

  • userConfig oem-specific user config

Returns

  • FBLPromise of AGMUserConfig

Update User Config by Key

Add or update user config by key

Requires write_userprofile scope.

-(FBLPromise<AGMUserConfig *> *) updateUserConfigByKey:(NSString *)key withConfig:(AGMUserConfig *)value

Parameters

  • key config key
  • value config value

Returns

  • FBLPromise of AGMUserConfig

Delete User Config by Key

Delete user config by key

Requires write_userprofile scope.

-(FBLPromise<NSNull *> *) deleteUserConfigByKey:(NSString *)key

Parameters

  • key key to delete

Returns

  • FBLPromise of NSNull

Get User Config

Gets previously stored key/value pairs.

Requires read_userprofile scope.

-(FBLPromise<AGMUserConfig *> *) getUserConfig

Returns

  • FBLPromise of AGMUserConfig

Get User Config by Key

Get user config by key

Requires read_userprofile scope.

-(FBLPromise<AGMUserConfig *> *) getUserConfigByKey:(NSString *)key

Parameters

  • key config key

Returns

  • FBLPromise of AGMUserConfig

Add User Image

Allows 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.

-(FBLPromise<AGMUserImage *> *) updateUserImage:(AGMUserImage *)image

Parameters

  • image image to add

Returns

  • FBLPromise of AGMUserImage

Delete User Image

Delete user image

Requires write_userprofile scope.

-(FBLPromise<NSNull *> *) deleteUserImage

Returns

  • FBLPromise of NSNull

Update User Profile Image

Add or update user profile image

Requires write_userprofile scope.

-(FBLPromise<AGMUserImage *> *) updateUserProfileImageById:(NSString *)profileId WithImage:(AGMUserImage *)image

Parameters

  • image image to add
  • profileId User Profile ID

Returns

  • FBLPromise of AGMUserImage

Delete user profile image

Remove user profile image

Requires write_userprofile scope.

-(FBLPromise<NSNull *> *) deleteUserProfileImageById:(NSString *)profileId

Parameters

  • profileId User Profile ID

Returns

  • FBLPromise of NSNull

Reset User Password

Native client user email reset - sends a password reset email

-(FBLPromise<NSNull *> *) public func resetUserPasswordForEmail:(NSString *)email

Parameters

  • email email address

Parameters

  • FBLPromise of NSNull

Login User

Login a user and set their token

-(FBLPromise<NSNull *> *) loginUserWithEmail:(NSString *)email withPassword:(NSString *)password withScope:(NSString *)scope
-(FBLPromise<NSNull *> *) loginUserWithEmail:(NSString *)email withPassword:(NSString *)password

Parameters

  • email email address
  • password password
  • scope scope

Returns

  • FBLPromise of NSNull

Login External User

Login an external (shadow account) user and set their token

-(FBLPromise<NSNull *> *) loginExternalUserWithId:(NSString *)externalUserId withCountryCode:(NSString *)countryCode withScope:(NSString *)scope
-(FBLPromise<NSNull *> *) loginExternalUserWithId:(NSString *)externalUserId withCountryCode:(NSString *)countryCode
-(FBLPromise<NSNull *> *) loginExternalUserWithId:(NSString *)externalUserId

Parameters

  • externalUserId external user id
  • countryCode country code
  • scope scope

Returns

  • FBLPromise of NSNull

Login Mobile User

Login a mobile user and set their token

-(FBLPromise<NSNull *> *) loginMobileUser:(NSString *)mobileNumber withCode:(NSString *)code withScope:(NSString *)scope
-(FBLPromise<NSNull *> *) loginMobileUser:(NSString *)mobileNumber withCode:(NSString *)code

Parameters

  • mobileNumber mobile number
  • code verification code
  • scope scope

Returns

  • FBLPromise of NSNull

Logout User

Logs the user out of the API, clearing any cached data present.

logoutUser

Is User Logged In?

Check if a user is logged in

-(BOOL) isUserLoggedIn

Returns

  • True if user is logged in.

Get Login Url

Get the url for the login page

-(FBLPromise<AGMURL *> *) getLoginUrlForScope:(NSString *)scope forService:(NSString *)service withState:(NSString *)state

Parameters

  • scope scope
  • service service to login to
  • state state

Returns

  • FBLPromise of AGMURL - the url of the login page

Create User

Regiser a new user. Assumes password been confirmed on client

-(FBLPromise<AGMAccessToken *> *) createUserWithFirstName:(NSString *)firstName withLastName:(NSString *)lastName withEmail:(NSString *)email withPassword:(NSString *)password

Parameters

  • firstName first name
  • lastName last name
  • email email address
  • password password

Returns

  • FBLPromise of AGMAccessToken

Get User Account Details

Get user account details by userid Gets the full account details.

Requires read_userprofile scope.

-(FBLPromise<AGMUserInfo *> *) getUser

Returns

  • FBLPromise of AGMUserInfo

Update User Account Details

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.

-(FBLPromise<AGMUserInfo *> *) updateUserWithUserInfo:(AGMUserInfo *)userinfo

Parameters

  • userInfo user info

Returns

  • FBLPromise of AGMUserInfo

Get User Profiles

Get user profiles

Requires read_userprofile scope.

-(FBLPromise<AGMUserProfiles *> *) getUserProfiles

Returns

  • FBLPromise of AGMUserProfiles

Update User Profile

Add or updates user profile

Requires write_userprofile scope.

-(FBLPromise<AGMUserProfile *> *) updateUserProfile:(AGMUserProfile *)userProfile

Parameters

  • userProfile User Profile

Returns

  • FBLPromise of AGMUserProfile

Update User Profile By Id

Update user profile details

Requires write_userprofile scope.

-(FBLPromise<AGMUserProfile *> *) updateUserProfileById:(AGMUserProfile *)userProfile withProfile:(NSString *)profileId

Parameters

  • userProfile User Profile
  • profileId User Profile ID

Returns

  • FBLPromise of UserProfile

Get User Profile By Id

Get user profile details

Requires read_userprofile scope.

-(FBLPromise<AGMUserProfile *> *) getUserProfileById:(NSString *)profileId

Parameters

  • profileId User Profile ID

Returns

  • FBLPromise of AGMUserProfile

Delete User Profile By Id

Delete a user profile

Requires write_userprofile scope.

-(FBLPromise<NSNull *> *) deleteUserProfileById:(NSString *)profileId

Parameters

  • profileId User Profile ID

Parameters

  • FBLPromise of NSNull

Verify User Mobile

Native client verification - verifies a user's mobile number

-(FBLPromise<NSNull *> *) verifyUserMobile:(NSString *)mobileNumbre withCode:(NSString *)code

Parameters

  • mobileNumber mobile number
  • code verification code

Parameters

  • FBLPromise of NSNull

Verify User Email

Native client verification - sends a verification email

-(FBLPromise<NSNull *> *) verifyUserEmail:(NSString *)email

Parameters

  • email email address

Returns

  • FBLPromise of NSNull

Check User Exists

Check if an account exists Check if an account exists by email address

-(FBLPromise<NSNull *> *) checkUserExistsByEmail: (NSString *)email withValidation:(BOOL)validate
-(FBLPromise<NSNull *> *) checkUserExistsByEmail: (NSString *)email

Parameters

  • email The Email address to look up
  • validate Flag to enable email address validation

Parameters

  • FBLPromise of NSNull

Get Support Documentation

Get help and support content Requires signin scope.

-(FBLPromise<AGMSupportDocumentation *> *) getSupportDocumentationForLanguage:(NSString *)language

Parameters

  • language Language code to look for; falls back to en

Returns

  • FBLPromise of AGMSupportDocumentation

Send Support Email

Sends support email

Requires signin scope.

-(FBLPromise<NSNull *> *) sendSupportEmail:(NSString *)supportEmail

Parameters

  • supportEmail email to send

Returns

  • FBLPromise of NSNull

Get User Services

-(FBLPromise<LinkedServiceList *> *) getUserServices

Gets a list of services the user has linked to their account.

Requires read_userprofile scope.

Returns

  • FBLPromise of LinkedServiceList

Get User Service

-(FBLPromise<LinkedService *> *) getUserService:(NSString *)serviceId

Gets details of a specific content service linked to the user's account, if available.

Requires read_userprofile scope.

Parameters

  • serviceId id of the service to fetch details of

Returns

  • FBLPromise of LinkedService

Start Service Authorization

Gets an authorize URI to start a OAuth2 flow with the content service.

Requires write_userprofile scope.

-(FBLPromise<AGMUserServiceAuthorizeDetails *> *) startServiceAuthorization:

Parameters

  • serviceId id of the content service.

Returns

  • FBLPromise of AGMUserServiceAuthorizeDetails

Obtain Service Token

Obtain or refresh a service access token

Requires write_userprofile scope.

-(FBLPromise<AGMUserServiceCredentials *> *) obtainServiceTokenForService: code:

Parameters

  • serviceId id of the content service.
  • code optional OAuth2 authorization code from the service.

Returns

  • FBLPromise of AGMUserServiceCredentials

Remove Service Token

Remove a service access token

Requires write_userprofile scope.

-(FBLPromise<NSNull *> *) removeServiceTokenForService:

Parameters

  • serviceId id of the content service.

Returns

  • FBLPromise of NSNull

Browse 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.

-(FBLPromise<AGMSearchResultsGroup *> *) browseService:(NSString *)service forParent:(NSString *)parent withStart:(NSNumber *)startindex andItemsPerPage:(NSNumber *)itemsperpage andChildren:(NSNumber *)children
-(FBLPromise<AGMSearchResultsGroup *> *) browseService:(NSString *)service forParent:(NSString *)parent withStart:(NSNumber *)startindex andItemsPerPage:(NSNumber *)itemsperpage
-(FBLPromise<AGMSearchResultsGroup *> *) browseService:(NSString *)service forParent:(NSString *)parent withStart:(NSNumber *)startindex
-(FBLPromise<AGMSearchResultsGroup *> *) browseService:(NSString *)service forParent:(NSString *)parent
-(FBLPromise<AGMSearchResultsGroup *> *) browseService:(NSString *)service withChildren:(NSNumber *)children
-(FBLPromise<AGMSearchResultsGroup *> *) browseService:(NSString *)service

Parameters

  • service The content service
  • parent Optional parent group for drill down
  • startindex Optional paging - the offset that items should start at - defaults to 0
  • itemsperpage Optional paging - the number of items to return in each bucket - defaults to 20

Returns

  • FBLPromise of AGMSearchResultsGroup

Get Artist

Get 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.

-(FBLPromise<AGMArtist *> *) getArtistById:

Parameters

  • artistId Artist id

Returns

  • FBLPromise of AGMArtist

Get Artist Songs

Gets an artist's albums or songs from a service based on our id

Requires search scope.

-(FBLPromise<AGMTrackListing *> *) getArtistSongsForId:(NSString *)artistId inService:(NSString *)service withItemsPerPage:(NSNumber *)itemsperpage andStartIndex:(NSNumber *)startindex
-(FBLPromise<AGMTrackListing *> *) getArtistSongsForId:(NSString *)artistId inService:(NSString *)service withItemsPerPage:(NSNumber *)itemsperpage
-(FBLPromise<AGMTrackListing *> *) getArtistSongsForId:(NSString *)artistId inService:(NSString *)service

Parameters

  • artistId Audiogum artist id
  • service The content service
  • startindex paging - the offset that items should start at - defaults to 0
  • itemsperpage paging - the number of items to return - defaults to 50

Returns

  • FBLPromise of AGMTrackListing

Get Artist Songs For Ref

Gets an artist's albums or songs from a service based on the service ref

Requires search scope.

-(FBLPromise<AGMTrackListing *> *) getArtistSongsForRef:(NSString *)artistId inService:(NSString *)service withItemsPerPage:(NSNumber *)itemsperpage andStartIndex:(NSNumber *)startindex

Parameters

  • ref Service ref for the artist
  • service The content service
  • startindex paging - the offset that items should start at - defaults to 0
  • itemsperpage paging - the number of items to return - defaults to 50

Returns

  • FBLPromise of AGMTrackListing

Get Artist Albums

Gets an artist's albums from a service based on our id

Requires search scope.

-(FBLPromise<AGMPlaylistListing *> *) getArtistAlbumsForId:(NSString *)artistId inService:(NSString *)service withItemsPerPage:(NSNumber *)itemsperpage andStartIndex:(NSNumber)startindex
-(FBLPromise<AGMPlaylistListing *> *) getArtistAlbumsForId:(NSString *)artistId inService:(NSString *)service withItemsPerPage:(NSNumber *)itemsperpage
-(FBLPromise<AGMPlaylistListing *> *) getArtistAlbumsForId:(NSString *)artistId inService:(NSString *)service

Parameters

  • artistId Audiogum artist id
  • service The content service
  • startindex paging - the offset that items should start at - defaults to 0
  • itemsperpage paging - the number of items to return - defaults to 50

Returns

  • FBLPromise of AGMPlaylistListing

Get Artist Albums For Ref

Gets an artist's albums from a service based on the service ref

Requires search scope.

-(FBLPromise<AGMPlaylistListing *> *) getArtistAlbumsForRef:(NSString *)ref inService:(NSString *)service withItemsPerPage:(NSNumber *)itemsperpage andStartIndex:(NSNumber)startindex

Parameters

  • ref The service ref
  • service The content service
  • startindex paging - the offset that items should start at - defaults to 0
  • itemsperpage paging - the number of items to return - defaults to 50

Returns

  • FBLPromise of AGMPlaylistListing

Get Artist Items For Ref

Gets an artist's items of a specific type from a service based on the service ref

Requires search scope.

-(FBLPromise<AGMSearchResultsGroup *> *) getArtistItemsForRef:(NSString *)ref inService:(NSString *)service ofType:(NSString *)itemtype withItemsPerPage:(NSNumber *)itemsperpage andStartIndex:(NSNumber *)startindex

Parameters

  • ref The service ref
  • service The content service
  • itemtype 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 0
  • itemsperpage paging - the number of items to return - defaults to 50

Returns

  • FBLPromise of AGMSearchResultsGroup

Search across content services. Returns search results in various buckets

  • e.g. Playlists, Radio Stations, Artists.

Requires search scope.

-(FBLPromise<AGMSearchResultsGroup *> *) search:(NSString *)term withItemsPerPage:(NSNumber *)itemsperpage forTypes:(NSArray<NSString *> *)type inServices:(NSArray<NSString *> *)service
-(FBLPromise<AGMSearchResultsGroup *> *) search:(NSString *)term withItemsPerPage:(NSNumber *)itemsperpage forTypes:(NSArray<NSString *> *)type
-(FBLPromise<AGMSearchResultsGroup *> *) search:(NSString *)term withItemsPerPage:(NSNumber *)itemsperpage
-(FBLPromise<AGMSearchResultsGroup *> *) search:(NSString *)term

Parameters

  • term Content query
  • itemsperpage Number of items in each bucket - default 3
  • type Optional filter parameter that limits types searched to those that are in this comma delimited list
  • service Optional filter parameter that limits the services searched to those that are in this list (assuming they are allowed for the user)

Returns

  • FBLPromise of AGMSearchResultsGroup

Get Album Tracks

Get tracks for an album

Requires search scope.

-(FBLPromise<AGMTrackListing *> *) getAlbumTracksForRef:(NSString *)ref inService:(NSString *)service withItemsPerPage:(NSNumber *)itemsperpage andStartIndex:(NSNumber *)startindex
-(FBLPromise<AGMTrackListing *> *) getAlbumTracksForRef:(NSString *)ref inService:(NSString *)service withItemsPerPage:(NSNumber *)itemsperpage
-(FBLPromise<AGMTrackListing *> *) getAlbumTracksForRef:(NSString *)ref inService:(NSString *)service

Parameters

  • service The content service
  • ref Service reference of parent
  • startindex Optional paging - the offset that items should start at - defaults to 0
  • itemsperpage Optional paging - the number of items to return - defaults to 50

Returns

  • FBLPromise of AGMTrackListing

Get Songs by Parent

Gets 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.

-(FBLPromise<AGMTrackListing *> *) getSongsByParentForType:(NSString *)type withRef:(NSString *)ref inService:(NSString *)service withItemsPerPage:(NSNumber *)itemsperpage andStartIndex:(NSNumber *)startindex
-(FBLPromise<AGMTrackListing *> *) getSongsByParentForType:(NSString *)type withRef:(NSString *)ref inService:(NSString *)service withItemsPerPage:(NSNumber *)itemsperpage 
-(FBLPromise<AGMTrackListing *> *) getSongsByParentForType:(NSString *)type withRef:(NSString *)ref inService:(NSString *)service

Parameters

  • type The resource type
  • service The content service
  • ref The content service resource reference
  • startindex Optional paging - the offset that items should start at - defaults to 0
  • itemsperpage Optional paging - the number of items to return - defaults to 50

Returns

  • FBLPromise of AGMTrackListing

Get Service Song

Gets a song by service reference.

Requires search scope.

-(FBLPromise<AGMTrack *> *) getServiceSongForRef:(NSString *)ref inService:(NSString *)service withItemsPerPage:(NSNumber *) itemsperpage andStartIndex:(NSNumber *)startindex
-(FBLPromise<AGMTrack *> *) getServiceSongForRef:(NSString *)ref inService:(NSString *)service withItemsPerPage:(NSNumber *) itemsperpage 
-(FBLPromise<AGMTrack *> *) getServiceSongForRef:(NSString *)ref inService:(NSString *)service

Parameters

  • ref The content service resource reference
  • service The content service
  • startindex Optional paging - the offset that items should start at - defaults to 0
  • itemsperpage Optional paging - the number of items to return - defaults to 50

Returns

  • FBLPromise of AGMTrack

Get Service Playlist

Gets a playlist or album by service reference.

Requires search scope.

-(FBLPromise<AGMPlaylist *> *) getServicePlaylistForType:(NSString *)type andRef:(NSString *)ref inService:(NSString *)service withItemsPerPage:(NSNumber *) itemsperpage andStartIndex:(NSNumber *)startindex
-(FBLPromise<AGMPlaylist *> *) getServicePlaylistForType:(NSString *)type andRef:(NSString *)ref inService:(NSString *)service withItemsPerPage:(NSNumber *) itemsperpage 
-(FBLPromise<AGMPlaylist *> *) getServicePlaylistForType:(NSString *)type andRef:(NSString *)ref inService:(NSString *)service

Parameters

  • type The resource type ("playlist" or "album")
  • ref The content service resource reference
  • service The content service
  • startindex Optional paging - the offset that items should start at - defaults to 0
  • itemsperpage Optional paging - the number of items to return - defaults to 50

Returns

  • FBLPromise of AGMPlaylist

Get Playlist Tracks

Get tracks for a playlist

Requires search scope.

-(FBLPromise<AGMTrackListing *> *) getPlaylistTracksForRef:(NSString *)ref inService:(NSString *)service withItemsPerPage:(NSNumber *)itemsperpage andStartIndex:(NSNumber *)startindex
-(FBLPromise<AGMTrackListing *> *) getPlaylistTracksForRef:(NSString *)ref inService:(NSString *)service withItemsPerPage:(NSNumber *)itemsperpage
-(FBLPromise<AGMTrackListing *> *) getPlaylistTracksForRef:(NSString *)ref inService:(NSString *)service

Parameters

  • service The content service
  • ref Service reference of parent
  • startindex Optional paging - the offset that items should start at - defaults to 0
  • itemsperpage Optional paging - the number of items to return - defaults to 50

Returns

  • FBLPromise of AGMTrackListing

Search Artists

Search artists

Requires search scope.

-(FBLPromise<AGMSearchResultsGroup *> *) searchArtist:(NSString *)term withItemsPerPage:(NSNumber *)itemsperpage inService:(NSString *)service
-(FBLPromise<AGMSearchResultsGroup *> *) searchArtist:(NSString *)term withItemsPerPage:(NSNumber *)itemsperpage
-(FBLPromise<AGMSearchResultsGroup *> *) searchArtist:(NSString *)term

Parameters

  • term Query to search for
  • itemsperpage Number of items in each bucket - default 20
  • startindex Page start position - default 0
  • service Service to search

Returns

  • FBLPromise of AGMSearchResultsGroup

Search Artists By Ids

Search artists

Requires search scope.

-(FBLPromise<AGMSearchResultsGroup *> *) searchArtistByIds:(NSString *)ids withItemsPerPage:(NSNumber *)itemsperpage inService:(NSString *)service
-(FBLPromise<AGMSearchResultsGroup *> *) searchArtistByIds:(NSString *)ids withItemsPerPage:(NSNumber *)itemsperpage
-(FBLPromise<AGMSearchResultsGroup *> *) searchArtistByIds:(NSString *)ids

Parameters

  • id IDs to obtain details for
  • itemsperpage Number of items in each bucket - default 20
  • service Service to search

Returns

  • FBLPromise of AGMSearchResultsGroup

Search By Type and Service

Single bucket results for paging Drill down into detailed results for paging through a bucket.

Requires search scope.

-(FBLPromise<AGMSearchResultsGroup *> *) searchBytType:(NSString *)type inService:(NSString *)service withTerm:(NSString *)term withItemsPerPage:(NSNumber *)itemsperpage andStartIndex:(NSNumber *)startindex
-(FBLPromise<AGMSearchResultsGroup *> *) searchBytType:(NSString *)type inService:(NSString *)service withTerm:(NSString *)term withItemsPerPage:(NSNumber *)itemsperpage
-(FBLPromise<AGMSearchResultsGroup *> *) searchBytType:(NSString *)type inService:(NSString *)service withTerm:(NSString *)term
-(FBLPromise<AGMSearchResultsGroup *> *) searchBytType:(NSString *)type inService:(NSString *)service

Parameters

  • type The bucket type
  • service The content service
  • term Content query
  • itemsperpage Number of items in each bucket - default 20
  • startindex Page start position - default 0

Returns

  • FBLPromise of AGMSearchResultsGroup

Get Genres

Get a list of genres. Includes popularity in the current country and localized name.

Requires search scope.

-(FBLPromise<AGMGenres *> *) getGenresWithItemsPerPage:(NSNumber *)itemsperpage andStartIndex:(NSNumber *)startindex
-(FBLPromise<AGMGenres *> *) getGenresWithItemsPerPage:(NSNumber *)itemsperpage
-(FBLPromise<AGMGenres *> *) getGenres

Parameters

  • startindex Paging - the offset that items should start at
  • itemsperpage Paging - the number of items to return

Returns

  • FBLPromise of AGMGenres

Get top artists for genres

Get the top artists (by popularity) for a selection of given genres

Requires search scope.

-(FBLPromise<AGMTopArtistsByGenre *> *) getTopArtistsForGenre:(NSString *)genre withItemsPerPage:(NSNumber *)itemsperpage andStartIndex:(NSNumber *)itemsperpage withFields:(NSString *)fields
-(FBLPromise<AGMTopArtistsByGenre *> *) getTopArtistsForGenre:(NSString *)genre withItemsPerPage:(NSNumber *)itemsperpage andStartIndex:(NSNumber *)itemsperpage
-(FBLPromise<AGMTopArtistsByGenre *> *) getTopArtistsForGenre:(NSString *)genre withItemsPerPage:(NSNumber *)itemsperpage
-(FBLPromise<AGMTopArtistsByGenre *> *) getTopArtistsForGenre:(NSString *)genre

Parameters

  • genre The genres to get topartists for
  • startindex Paging - the offset that items should start at
  • itemsperpage Paging - the number of items to return
  • fields The fields to return

Returns

  • FBLPromise of AGMTopArtistsByGenre

Get Top Artists

The most popular artists across a range of genres, merged together.

Requires search scope.

-(FBLPromise<AGMTopArtists *> *) getTopArtistsWithItemsPerPage:(NSNumber *)itemsperpage withFields:(NSString *)fields
-(FBLPromise<AGMTopArtists *> *) getTopArtistsWithItemsPerPage:(NSNumber *)itemsperpage
-(FBLPromise<AGMTopArtists *> *) getTopArtists

Parameters

  • itemsperpage Paging - the number of items to return
  • fields The fields to return

Returns

  • FBLPromise of AGMTopArtists

Create Playable

Request 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.

-(FBLPromise<AGMPlayable *> *) createPlayable:(AGMCreatePlayableRequest *)playableRequest

Parameters

  • playableRequest Information required to create a user playable

Returns

  • FBLPromise of AGMPlayable

Get Playable Tracks

Get 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.

-(FBLPromise<AGMPlayableTracks *> *) getPlayableTracks:(NSString *)playableId withStart:(NSNumber *)startindex andItemsPerPage:(NSNumber *)itemsperpage andStreamUrls:(NSNumber *)streamUrls

Parameters

  • playableId id of playable
  • startindex the offset that items should start at - defaults to 0
  • itemsperpage Optional paging - the number of items to return - defaults to 50
  • streamUrls Optionally omit stream urls (false). Default (true) indicates include where applicable

Returns

  • FBLPromise of AGMPlayableTracks

Delete Playable

Deletes a specific playable based on its id

Requires write_playlists scope.

-(FBLPromise<NSNull *> *) deletePlayable:(NSString *)playableId

Parameters

  • playableId id of playable

Returns

  • Promise of Void

Get User Playable

Get the basic details of a specific playable based on its id (note: this is not for playback purposes)

Requires write_playlists scope.

-(FBLPromise<AGMPlayable *> *) getUserPlayable:(NSString *)playableId

Parameters

  • playableId id of playable

Returns

  • FBLPromise of AGMPlayable

Get User Playable Items

Get the details including items of a specific playable based on its id (note: this is not for playback purposes)

Requires read_playlists scope.

-(FBLPromise<AGMPlayableTracks *> *)  getUserPlayableItems:(NSString *)playableId
-(FBLPromise<AGMPlayableTracks *> *)  getUserPlayableItemsWithPlayableId:(NSString * _Nonnull)playableId itemsPerPage:(NSInteger)itemsPerPage startIndex:(NSInteger)startIndex

Parameters

  • playableId id of playable
  • startindex the offset that items should start at - defaults to 0
  • itemsperpage optional paging - the number of items to return - defaults to 50

Returns

  • FBLPromise of AGMPlayableTracks

Refresh Stream Urls

Refresh streaming urls on behalf of the user for specific items from a service, for the case of time-limited content

Requires write_playlists scope.

-(FBLPromise<AGMTrackListing *> *) refreshStreamUrls:(NSString *)playableId forService:(NSString *)service withTrackIds:([NSString] *)trackIds

Parameters

  • playableId id of playable
  • service service
  • trackIds track ids to refresh

Returns

  • FBLPromise of AGMTrackListing

Authenticate for Voice

-(FBLPromise<NSNull *> *) authenticateForVoice

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.

Returns

  • FBLPromise of NSNull

Open Voice Session

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.

-(FBLPromise<NSNull *> *) openVoiceSessionWithProperties:(AGMVoiceProperties *)voiceProperties andDelegate:(AGMVoiceDelegate *)delegate

Parameters

  • 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.

Returns

  • FBLPromise of NSNull

Send Voice Terminator

Sends a voice terminator

sendVoiceTerminatorWithError:(NSError *)error

Parameters

  • error error

Send Voice Message

Send a string message to the voice service.

See https://www.audiogum.com/developers/docs/naturallanguageunderstanding.html for more details.

sendVoiceStringMessage:(NSString *)message withError:(NSError *)error

Parameters

  • message Message to be sent to voice service
  • error error

Send Voice Data Message

Send a message as data to the voice service.

See https://www.audiogum.com/developers/docs/naturallanguageunderstanding.html for more details.

sendVoiceDataMessage:(NSData *)message withError:(NSError *)error

Parameters

  • message Data to be sent to voice service
  • error error

Close Voice Session

Closes the active voice session, if any is currently connected.

See https://www.audiogum.com/developers/docs/naturallanguageunderstanding for more details.

-(void) closeVoiceSessionWithError:(NSError *)error throws

Generate Response Audio

-(FBLPromise<AGMRespond *> *) generateResponseAudio:(NSString *)phraseKey withLanguageCode:(NSString *)languageCode

Generates an audio response for the specified phrase in the language desired.

Requires speech scope

Parameters

  • 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.

Returns

  • FBLPromise of AGMRespond

Get Speech Suggestions

-(FBLPromise<AGMSpeechSuggestionResponse *> *) getSpeechSuggestions
-(FBLPromise<AGMSpeechSuggestionResponse *> *) getSpeechSuggestionsForNowPlaying:(AGMSpeechNowPlaying *)nowPlaying

Retrieves examples of speech requests that the user can make to the Audiogum service.

Requires speech scope

Parameters

  • nowPlaying optionally supply the current playing information for more personalised speech examples.

Returns

  • FBLPromise of AGMSpeechSuggestionResponse

Make Speech Request With Action Text

-(FBLPromise<AGMTextToActionRequest *> *) makeSpeechRequestWithActionText:(AGMTextToActionResponse *)request

Convert the text of an instruction into the action that should be performed.

Requires speech scope

Parameters

  • request information about the request to be made.

Returns

  • FBLPromise of AGMTextToActionResponse

Get Remote Contol Details

Get remotecontrol details of connected remote control device

See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.

-(FBLPromise<AGMRemoteControlSupportedActionsDetails *> *) getRemoteControlDetailsForToken:(NSString *)remoteControlToken

Parameters

  • remoteControlToken Remote control token

Returns

  • FBLPromise of AGMRemoteControlSupportedActionsDetails

Send Remote Control Command

Send a command to a remote control device

See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.

-(FBLPromise<NSNull *> *) sendRemoteControlCommand:(AGMRemoteControlCommand *)command

Parameters

  • command Remote control command

Returns

FBLPromise of NSNull

Get Remote Control Player State

Get player state from a connected remote control device

See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.

-(FBLPromise<AGMDevicePlayerDetails *> *) getRemoteControlDevicePlayerDetailsForToken:(NSString *)remoteControlToken

Parameters

  • remoteControlToken Remote control token

Returns

  • FBLPromise of AGMDevicePlayerDetails

Get Remote Control Device State

Get device state from a connected remote control device

See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.

-(FBLPromise<AGMRemoteControlDeviceDetails *> *) getRemoteControlDeviceDetailsForToken:(NSString *)remoteControlToken

Parameters

  • remoteControlToken Remote control token

Returns

  • FBLPromise of AGMRemoteControlDeviceDetails

Get Remote Control Preset State

Get preset state from a connected remote control device

See https://www.audiogum.com/developers/docs/remotecontrol.html for more details.

-(FBLPromise<AGMRemoteControlDevicePresetDetails *> *)getRemoteControlDevicePresetDetailsForToken:(NSString *)remoteControlToken

Parameters

  • remoteControlToken Remote control token

Returns

  • FBLPromise of AGMRemoteControlDevicePresetDetails

Get Taste Profile

- (FBLPromise<AGMUserProfile *> *)getTasteProfile

Gets the taste profile.

Returns

  • FBLPromise of TasteProfile

Add to Taste Profile

- (FBLPromise<NSNull *> *)addToTasteProfile:(AGMTasteProfile *)itemsToAdd

Add items to the taste profile

Parameters

  • itemsToAdd Items to add to the taste profile

Returns

  • FBLPromise of Void

Add to Taste Profile by Name

- (FBLPromise<NSNull *> *)addToTasteProfileByName:(AGMTasteProfile *)itemsToAdd

Add items to the taste profile by name

Parameters

  • itemsToAdd Items to add to the taste profile by name

Returns

  • FBLPromise of Void

Check Artist Taste State by Name

- (FBLPromise<AGMTasteMatch *> *)checkArtistTasteStateByName:<#(NSString * _Nonnull)#>

Check artist taste state by name

Parameters

  • name The name to check

Returns

  • FBLPromise of AGMTasteMatch

Add Artists to Taste Profile

- (FBLPromise<NSNull *> *)addArtistsToTasteProfile:([AGMArtist] *)artists

Add artists to the taste profile

Parameters

  • artists Artists to add to the taste profile

Returns

  • FBLPromise of Void

Add Internet Radio Stations to Taste Profile

- (FBLPromise<NSNull *> *)addAInternetRadiosToTasteProfile:([AGMInternetRadio] *)internetRadios

Add Internet Radio Stations to the taste profile

Parameters

  • internetRadios Internet Radio Stations to add to the taste profile

Returns

  • FBLPromise of Void

Add Playlists to Taste Profile

- (FBLPromise<NSNull *> *)addPlaylistsToTasteProfile:([AGMPlaylist] *)playlists

Add Playlists to the taste profile

Parameters

  • playlists Playlists to add to the taste profile

Returns

  • FBLPromise of Void

Add Albums to Taste Profile

- (FBLPromise<NSNull *> *)addAlbumToTasteProfile:([AGMPlaylist] *)albums

Add Albums to the taste profile

Parameters

  • albums Albums to add to the taste profile

Returns

  • FBLPromise of Void

Add Songs to Taste Profile

- (FBLPromise<NSNull *> *)addSongsToTasteProfile:([AGMSong] *)songs

Add Songs to the taste profile

Parameters

  • songs Songs to add to the taste profile

Returns

  • FBLPromise of Void

Add Likes to Taste Profile

- (FBLPromise<NSNull *> *)addArtistsToTasteProfile:([AGMArtist] *)artists withInternetRadios:([AGMInternetRadio] *)internetradios withPlaylists:([AGMPlaylist] *)playlists withAlbums:([AGMPlaylist] *)albums withSongs:([Track] *)songs

Add Likes to the taste profile

Parameters

  • artists Artists to add to the taste profile
  • internetRadios Internet Radio Stations to add to the taste profile
  • playlists Playlists to add to the taste profile
  • albums Albums to add to the taste profile
  • songs Songs to add to the taste profile

Returns

  • FBLPromise of Void

Delete from Taste Profile

- (FBLPromise<NSNull *> *)deleteFromTasteProfile:(AGMTasteProfile *)itemsToDelete

Removes multiple items from the taste profile

Parameters

  • itemsToDelete Items to delete from the taste profile

Returns

  • FBLPromise of Void

Delete Artists from Taste Profile

- (FBLPromise<NSNull *> *)deleteArtistsFromTasteProfile:([AGMArtist] *)artists

Delete artists from the taste profile

Parameters

  • artists Artists to delete from the taste profile

Returns

  • FBLPromise of Void

Delete Internet Radio Stations from Taste Profile

- (FBLPromise<NSNull *> *)deleteAInternetRadiosFromTasteProfile:([AGMInternetRadio] *)internetRadios

Delete Internet Radio Stations from the taste profile

Parameters

  • internetRadios Internet Radio Stations to delete from the taste profile

Returns

  • FBLPromise of Void

Delete Playlists from Taste Profile

- (FBLPromise<NSNull *> *)deletePlaylistsFromTasteProfile:([AGMPlaylist] *)playlists

Delete Playlists from the taste profile

Parameters

  • playlists Playlists to delete from the taste profile

Returns

  • FBLPromise of Void

Delete Albums from Taste Profile

- (FBLPromise<NSNull *> *)deleteAlbumFromTasteProfile:([AGMPlaylist] *)albums

Delete Albums from the taste profile

Parameters

  • albums Albums to delete from the taste profile

Returns

  • FBLPromise of Void

Delete Songs from Taste Profile

- (FBLPromise<NSNull *> *)deleteSongsFromTasteProfile:([AGMSong] *)songs

Delete Songs from the taste profile

Parameters

  • songs Songs to delete from the taste profile

Returns

  • FBLPromise of Void

Delete Likes from Taste Profile

- (FBLPromise<NSNull *> *)deleteArtistsFromTasteProfile:([AGMArtist] *)artists withInternetRadios:([AGMInternetRadio] *)internetradios withPlaylists:([AGMPlaylist] *)playlists withAlbums:([AGMPlaylist] *)albums withSongs:([Track] *)songs

Delete Likes from the taste profile

Parameters

  • artists Artists to delete from the taste profile
  • internetRadios Internet Radio Stations to delete from the taste profile
  • playlists Playlists to delete from the taste profile
  • albums Albums to delete from the taste profile
  • songs Songs to delete from the taste profile

Returns

  • FBLPromise of Void

Get Taste Genre Tags

- (FBLPromise<AGMTagsProfile *> *)getTasteGenreTags
- (FBLPromise<AGMTagsProfile *> *)getTasteGenreTagsWithTagsPerItem:(NSInteger)tagsPerItem

Gets the top genre tags matching user's profile

Parameters

  • tagsPerItem optionally limit the tag values used per item to the specified number of most important values

Returns

  • FBLPromise of the user's genre taste profile tags

Send Analytics Events

-(FBLPromise<NSNull *> *)sendAnalyticsWithEvents:(NSArray<AGMEvent *> *)events
-(FBLPromise<NSNull *> *)sendAnalyticsWithEvents:(NSArray<AGMEvent *> *)events withValidation:(BOOL)validateOnly

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.

Parameters

  • events the collection of events to send.
  • validateOnly if true, the events will validated but not recorded. Defaults to false.

Returns

  • FBLPromise of NSNull

Upload Log

-(FBLPromise<NSNull *> *)uploadLogWithDeviceId:(NSString *)deviceId logType:(NSString *)logType content:(NSString *)content

Upload a log or crash dump file.

Requires write_device scope.

Parameters

  • deviceId The id of the device the log relates to.
  • logType The type of log to be sent.
  • content The content to be logged.

Returns

  • FBLPromise of NSNull

Get App Release

- (FBLPromise<AGMAppRelease *> *) getAppReleaseForRegion:(NSString *)region onPlatform:(NSString *)platform inAppStore:(NSString *)appstore withVersion:(NSString *)version
	withLanguage:(NSString *)language withAltApp:(NSString *)altapp withPlatformVersion:(NSString *)platformveresion withDeviceManufacturer:(NSString *)deviceManufacturer withDeviceName(NSString *)devicename

Fetches details of any available app update.

Parameters

  • 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 language
  • altapp Codename of alternative app. Omit this for releases of the default app.
  • platformversion Optional operating system version
  • devicemanufacturer Optional device manufacturer
  • devicename Optional device name

Returns

  • a Promise containing an AppRelease describing the available update, or nil if none available.

Register Device

- (FBLPromise<NSNull *> *)registerDevice

Registers the device making the SDK calls with the Audiogum API. This is required to ensure your analytics data is as accurate as possible.

Returns

  • Promise of Void

Get User Devices

- (FBLPromise<AGMDeviceList *> *)getUserDevices
- (FBLPromise<AGMDeviceList *> *)getUserDevicesOfType: (NSArray<NSString *> *)ofType

Lists the devices this user has been associated with.

Parameters

  • ofType An optional array of device types to fetch.

Returns

  • a DeviceList containing information about the devices associated to the current user.

Get User Owned Devices

- (FBLPromise<AGMDeviceList *> *)getUserOwnedDevices

Lists the devices currently owned by the current user. Note that the full device info is not shown here.

Returns

  • a DeviceList containing information about the user's currently owned devices.

Register User Owned Device

- (FBLPromise<NSNull *> *)registerUserOwnedDeviceWithId: (NSString *)deviceid

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.

Parameters

  • deviceid the id of the device being marked as owned.

Returns

  • Promise of Void