Analytics

The PSPDFKit Analytics API allows you to easily collect usage data based on a user’s activity taking place in PSPDFKit components.

The PSPDFKit Analytics API consists of:

Integration

Enable Analytics

The PSPDFKit Analytics API is disabled by default, so you first need to enable it to use it:

1
PSPDFKitGlobal.sharedInstance.analytics.enabled = true
1
PSPDFKitGlobal.sharedInstance.analytics.enabled = YES;

Next you need to implement the PSPDFAnalyticsClient protocol. Your PSPDFAnalyticsClient is a place to process PSPDFKit events and pass them to the analytics service of your choice.

Be aware that events are delivered on a background queue.

Create an instance of your PSPDFAnalyticsClient when the app launches (preferably at the same time you’re configuring the PSPDFKit license) and register it with PSPDFAnalytics:

1
2
let analyticsClient = YourAnalyticsClient()
PSPDFKitGlobal.sharedInstance.analytics.add(analyticsClient)
Copy
1
2
id<PSPDFAnalyticsClient> analyticsClient = [[YourAnalyticsClient alloc] init];
[PSPDFKitGlobal.sharedInstance.analytics addAnalyticsClient:analyticsClient];

You can find a simple PSPDFAnalyticsClient implementation in AnalyticsClientExample.swift in the PSPDFKit Catalog app.

Events

An event has a name and a dictionary of additional parameters. Event parameters are of standard, JSON-friendly types.

All PSPDFKit event names are prefixed with pspdf_ and use underscore_case.

You can find the complete list of PSPDFKit events and parameters in the PSPDFAnalyticsEvents.h header and in the list below.

  • PSPDFAnalyticsEventNameDocumentLoad (raw value: pspdf_load_document)

    1
    2
    3
    
    	This signifies that the user has loaded a document.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNamePageChange (raw value: pspdf_change_page)

    1
    2
    3
    
    	This signifies that the user changed the page.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameAnnotationCreationModeEnter (raw value: pspdf_enter_annotation_creation_mode)

    1
    2
    3
    
    	This signifies that the user opened the annotation toolbar.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameAnnotationCreationModeExit (raw value: pspdf_exit_annotation_creation_mode)

    1
    2
    3
    
    	This signifies that the user closed the annotation toolbar.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameAnnotationCreatorDialogShow (raw value: pspdf_show_annotation_creator_dialog)

    1
    2
    3
    
    	This signifies that the annotation creator dialog was shown to the user.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameAnnotationCreatorDialogCancel (raw value: pspdf_cancel_annotation_creator_dialog)

    1
    2
    3
    
    	This signifies that the annotation creator dialog was canceled by the user.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameAnnotationCreatorSet (raw value: pspdf_set_annotation_creator)

    1
    2
    3
    
    	This signifies that the annotation creator dialog was confirmed by the user, thereby setting a creator name.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameAnnotationSelect (raw value: pspdf_select_annotation)

    Copy
    1
    2
    3
    4
    5
    
    	This signifies that the user selected an annotation, e.g. by tapping it.
    
    	Attributes:
    
    	- Key: `PSPDFAnalyticsEventAttributeNameAnnotationType`. Value: `PSPDFAnnotationString` of the selected annotation.
    
  • PSPDFAnalyticsEventNameAnnotationCreate (raw value: pspdf_create_annotation)

    Copy
    1
    2
    3
    4
    5
    
    	This signifies that the user created an annotation and added it to the document.
    
    	Attributes:
    
    	- Key: `PSPDFAnalyticsEventAttributeNameAnnotationType`. Value: `PSPDFAnnotationString` of the created annotation.
    
  • PSPDFAnalyticsEventNameAnnotationDelete (raw value: pspdf_delete_annotation)

    Copy
    1
    2
    3
    4
    5
    
    	This signifies that the user deleted an annotation from the document.
    
    	Attributes:
    
    	- Key: `PSPDFAnalyticsEventAttributeNameAnnotationType`. Value: `PSPDFAnnotationString` of the deleted annotation.
    
  • PSPDFAnalyticsEventNameAnnotationInspectorShow (raw value: pspdf_show_annotation_inspector)

    Copy
    1
    2
    3
    
    	This signifies that the user opened the annotation inspector for editing annotation properties, either via the annotation toolbar or by editing an existing annotation.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameTextSelect (raw value: pspdf_select_text)

    1
    2
    3
    
    	This signifies that the user has selected text on the document.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameOutlineOpen (raw value: pspdf_open_outline_view)

    1
    2
    3
    
    	This signifies that the user opened the outline containing the document outline, annotations, and bookmarks.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameOutlineElementSelect (raw value: pspdf_tap_outline_element_in_outline_list)

    1
    2
    3
    
    	This signifies that the user tapped an outline element in the outline view.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameOutlineAnnotationSelect (raw value: pspdf_tap_annotation_in_outline_list)

    Copy
    1
    2
    3
    4
    5
    
    	This signifies that the user tapped an annotation in the outline view.
    
    	Attributes:
    
    	- Key: `PSPDFAnalyticsEventAttributeNameAnnotationType`. Value: `PSPDFAnnotationString` of the selected annotation.
    
  • PSPDFAnalyticsEventNameThumbnailGridOpen (raw value: pspdf_open_thumbnail_grid)

    1
    2
    3
    
    	This signifies that the user opened the thumbnail grid view.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameDocumentEditorOpen (raw value: pspdf_open_document_editor)

    1
    2
    3
    
    	This signifies that the user opened the Document Editor.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameDocumentEditorAction (raw value: pspdf_perform_document_editor_action)

    Copy
    1
    2
    3
    4
    5
    
    	This signifies that the user performed an action inside the Document Editor.
    
    	Attributes:
    
    	- Key: `PSPDFAnalyticsEventAttributeNameAction`. Value: One of the `PSPDFAnalyticsEventAttributeValueAction`s that was performed by the user. For example, `PSPDFAnalyticsEventAttributeValueActionInsertNewPage`.
    
  • PSPDFAnalyticsEventNameBookmarkAdd (raw value: pspdf_add_bookmark)

    1
    2
    3
    
    	This signifies that the user added a bookmark to the document.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameBookmarkEdit (raw value: pspdf_edit_bookmarks)

    1
    2
    3
    
    	This signifies that the user has entered bookmark-editing mode inside the bookmark list.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameBookmarkRemove (raw value: pspdf_remove_bookmark)

    1
    2
    3
    
    	This signifies that the user has deleted a bookmark from the document.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameBookmarkSort (raw value: pspdf_sort_bookmark)

    1
    2
    3
    
    	This signifies that the user changed the order of a bookmark item in the bookmark list.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameBookmarkRename (raw value: pspdf_rename_bookmark)

    1
    2
    3
    
    	This signifies that the user renamed a bookmark.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameBookmarkSelect (raw value: pspdf_tap_bookmark_in_bookmark_list)

    1
    2
    3
    
    	This signifies that the user tapped a bookmark in the bookmark list.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameSearchStart (raw value: pspdf_start_search)

    1
    2
    3
    
    	This signifies that the user started a search in the document e.g. by pressing the search icon.
    
    	No attributes.
    
  • PSPDFAnalyticsEventNameSearchResultSelect (raw value: pspdf_select_search_result)

    1
    2
    3
    
    	This signifies that the user selected a search result after searching the document.
    
    		No attributes.
    
  • PSPDFAnalyticsEventNameShare (raw value: pspdf_share)

    Copy
    1
    2
    3
    4
    5
    
    	This signifies that the user shared the document using the share sheet.
    
    	Attributes:
    
    	- Key: `PSPDFAnalyticsEventAttributeNameActivityType`. Value: Activity type the user selected as string.
    
  • PSPDFAnalyticsEventNameToolbarMove (raw value: pspdf_move_toolbar)

    1
    
    This signifies that the toolbar was moved to a different location.
    

    Attributes:

    • Key: PSPDFAnalyticsEventAttributeValueToolbarPosition. Value: PSPDFFlexibleToolbarPosition of the destination.

Custom Events

The PSPDFKit events pipeline can also be used to deliver custom events.

Extend the PSPDFAnalyticsEventName type with your custom events:

1
2
3
extension PSPDFAnalyticsEventName {
    static var someCustomAction = PSPDFAnalyticsEventName(rawValue: "some_custom_action")
}
Copy
1
2
PSPDF_EXPORT PSPDFAnalyticsEventName const PSPDFAnalyticsEventNameSomeCustomAction; // in *.h
PSPDFAnalyticsEventName const PSPDFAnalyticsEventNameSomeCustomAction = @"some_custom_action"; // in *.m

Then use the PSPDFAnalytics object to deliver them:

1
PSPDFKitGlobal.sharedInstance.analytics.logEvent(.someCustomAction)
1
[PSPDFKitGlobal.sharedInstance.analytics logEvent:PSPDFAnalyticsEventNameSomeCustomAction];

The event in the above example will be dispatched to all registered PSPDFAnalyticsClient instances.