Progression API

Level progression API

ironSource App Analytics provides users’ progression analysis, such as levels completions and wins percentage. Furthermore,  when using this API, users’ level progression can be analyzed. Which level they started, completed or failed.

    Note: The progression API does not require any pre-init settings

    // The user level progression API
    +(void)updateProgress:(ISAnalyticsUserProgress *_Nonnull) userProgress; 
    // The user level progression API
    static func updateProgress(userProgress : ISAnalyticsUserProgress)


    • ISAnalyticsUserProgress userProgress– The object that represents the progression event

    ISAnalyticsUserProgress Object

    This object and it’s properties define all the required information regarding a progression event. Levels 1, 2 and 3 represent 3 hierarchy structure in the game. For example, can be used to distinguish between main and side levels, or represent a world, phases within that world and levels of a phase. You can implement one or more levels hierarchy based on what suits your game best


    • ISAnalyticsUserProgress(level1 : String) – The main level in the game

    Set methods:

    • state(state : ISAnalyticsProgressState) – An enumerated value of the user progression type (mandatory)
      • BEGIN
      • COMPLETE
      • FAILED
    • level2(level2 : String) – The secondary (in hierarchy) level in the game (optional)
    • level3(level3 : String) – The third (in hierarchy) level in the game (optional)
    • score(score : Int) – The score upon the progress update. 0 to represent no change in score or no score (mandatory)
    • attempt(amount : Int)The number of the attempt of the level (optional)

    Important! The value of the variable “attempt” starts from 1 (not from 0)

    Example of level progression update API

    // Examples of using the user progression API:
    // Start a level
    ISAnalyticsUserProgress *userProgress_start = [[[[ISAnalyticsUserProgress alloc] initWithLevel1:@"level_1"]score:0]state:ISAnalyticsProgressStateBEGIN]attempt:1];
    [IronSourceAnalytics updateProgress:userProgress_start];
    // Complete with score
    ISAnalyticsUserProgress *userProgress_score = [[[[ISAnalyticsUserProgress alloc] initWithLevel1:@"level_1"]score:99]state:ISAnalyticsProgressStateCOMPLETE]attempt:1];
    [IronSourceAnalytics updateProgress:userProgress_score];
    // Complete without score
    ISAnalyticsUserProgress *userProgress_no_score = [[[[ISAnalyticsUserProgress alloc] initWithLevel1:@"level_1"]score:0]state:ISAnalyticsProgressStateCOMPLETE]attempt:1];
    [IronSourceAnalytics updateProgress:userProgress_no_score];
    // Failed a level
    ISAnalyticsUserProgress *userProgress_fail = [[[[ISAnalyticsUserProgress alloc] initWithLevel1:@"level_1"]score:0]state:ISAnalyticsProgressStateFAILED]attempt:1];
    [IronSourceAnalytics updateProgress:userProgress_fail];
    // Examples of using the user progression API:
    // Start a level
    var userProgress_start = ISAnalyticsUserProgress(level1: "level_1").score(0).state(ISAnalyticsProgressState.BEGIN).score(1)
    // Complete with score
    var userProgress_score = ISAnalyticsUserProgress(level1: "level_1").score(99).state(ISAnalyticsProgressState.COMPLETE).score(1)
    // Complete without score
    var userProgress_no_score = ISAnalyticsUserProgress(level1: "level_1").score(0).state(ISAnalyticsProgressState.COMPLETE).score(1)
    // Failed a level
    var userProgress_fail = ISAnalyticsUserProgress(level1: "level_1").score(0).state(ISAnalyticsProgressState.FAILED).score(1)

    Custom activity API

    Use this API to update any user movement, click within the application or any other custom event, that are not related to level progression

    // The users actions API
    +(void)updateCustomActivity:(ISAnalyticsUserActivity *_Nonnull) appActivity;
    // The users actions API
    IronSourceAnalytics.updateCustomActivity(appActivity : ISAnalyticsUserActivity);


    • ISAnalyticsUserActivity appActivity – The object that represents the activity event

    ISAnalyticsUserActivity Object

    This object and it’s properties define all the required information regarding a user activity event


    • initWithName:(NSString *) name – The name of the activity to be analyzed

    Set methods:

    • property:(NSString *) property – A specific property of the activity (optional)

    Example of user action update API

    // Example of user activity within the application without attribute
    ISAnalyticsUserActivity *adOpen = [[ISAnalyticsUserActivity alloc] initWithName:@"ad_open"];
    [IronSourceAnalytics updateCustomActivity:adOpen];
    [IronSourceAnalytics updateCustomActivity:[[ISAnalyticsUserActivity alloc] initWithName:@"upload_picture"]];
    // Examples of user activity within the application with attribute
    ISAnalyticsUserActivity *inShop = [[[ISAnalyticsUserActivity alloc] initWithName:@"in_shop"] property:@"next_items"];
    [IronSourceAnalytics updateCustomActivity:inShop];
    [IronSourceAnalytics updateCustomActivity:[[ISAnalyticsUserActivity alloc] initWithName:@"page_open"] property:@"clan"]];
    ISAnalyticsUserActivity *clanPage = [[[ISAnalyticsUserActivity alloc] initWithName:@"clan_page"] property:@"join_clan"];
    [IronSourceAnalytics updateCustomActivity:clanPage];
    [clanPage property:@"left_clan"];
    [IronSourceAnalytics updateCustomActivity:clanPage];
    // Example of user activity within the application without attribute
    var adOpen = ISAnalyticsUserActivity(name: "ad_open")
    var uploadPicture = ISAnalyticsUserActivity(name: "upload_picture")
    // Examples of user activity within the application with attribute
    var pageOpenShop = ISAnalyticsUserActivity(name: "page_open").property("shop")
    var inShop = ISAnalyticsUserActivity(name: "in_shop").property("next_items")
    var pageOpen = ISAnalyticsUserActivity(name: "page_open").property("clan")
    var clanPage = ISAnalyticsUserActivity(name: "clan_page").property("join_clan")