Our documentation is changing, please click here to enjoy it!

Skip to end of metadata
Go to start of metadata

Tagging relevant information regarding your user profiles and their behaviours is crucial to send personalized and valuable messages.

Although the Accengage SDK collects by default certain useful information (such as install date, last open date, number of visits, device model ...), it also offers a number of advanced tagging and tracking features for app developers, that will allow you to target notifications, trigger messages at the right time, customize the user experience and analyze your campaign and application performance.

It is important that you check with the product or marketing team what type of actions they would like to perform, so that you can determine which information needs to be tagged. Most of the time they will provide you with a "tagging plan" which lists all of these.

However, a strategy could be to first implement a minimal version of Accengage in order to speed up the process and learn faster, then implement the tagging plan at a later stage for more relevant messages.

In the following section, we will look at the various options that you can enjoy to collect and use the right information:

  • enrich user profile, thanks to custom device information (or User Attributes), which are very useful for targeting and message personalization
  • tag user location, for geolocation targeting
  • tag user behaviours, thanks to events which offer many benefits (targeting, triggering and measurement), as well as views
  • register users to static lists, in order to manage preferences

If the information you would like to track is inside a webview, please see the Advanced section here

7.1 User profile

7.1.1 Enrich User profile with custom device information (or User Attributes)

In order to send well-targeted and personalized messages, Accengage lets you enrich your user profiles with additional relevant information, called custom device information.

These are very important for campaign targeting, as well as message personalization.

For instance, if you tag and update the first name of a user, you will be able to personalize a message with "Hello ${firstname}".

Traditional usage of custom device information for instance include first name, account ID (to match with external systems), total number of purchases, last purchased product, last purchase date, favorite product... They can be numeric values (set values, or incremental), strings, dates...

Note

Unlike events, the values of these custom device info are unique per user. This means the user's associated fields are single-value type fields and each update will erase currently stored values except when it's an incrementation (or decrementation).

By implementing the library in your app, you will automatically gather certain information about your app users : their device model, OS version, language, country, time zone, app version, install date, the number of visits and more...

The Accengage library lets you also collect additional custom device information, which can be attached to the user profile through custom database fields.

If the information you would like to enrich is inside a webview, please see the Advanced section here.

Important

Make sure that your custom_field is already created in the database (targeting > database scheme > add a field). Otherwise, the data will be ignored !
Check our user guide to have an overview of the database associated to your app and how to create a new field.

To enrich the user profile, and once the database scheme has been updated, you can add additional custom data (or User Attributes) using the updateDeviceInformation:withCompletionHandler: method.

First, create the device information set:

    Set, delete, increment or decrement the parameters (device information) in a following way:

      And finally call the appropriate SDK method:

        7.1.2 User geolocation

        You can benefit from your user's location data to target them using their past location.

        The location data are updated when the user opens the application.

        Note

        This user geolocation targeting is not to be confused with real-time geofencing which allows for campaign triggering based on real-time geolocation. See Geofence part.

        To update the user's current location, call the following method with a CLLocation object:

          7.1.3 Static lists subscriptions

          With Accengage, you can use two types of segments : Dynamic segments and Static lists.

          A Dynamic Segment is a segment which is defined by one or more criteria. Therefore, it may change as the values in the database are collected, imported, deleted and modified.

          A Static List is a set of mobile users whose volume is static at a given time.

          Unlike a Dynamic Segment whose volume can evolve according to the criteria defined in the interface, a Static List is a set of mobile users whose volume is static at a given time, in order, for example, to be used during a specific campaign or as an exclusion of a dynamic segment. Once created, a Static List can be populated through the SDK.

          The library provides several methods to manage the subscription to static lists.

          Important

          First, make sure that you've created your static list with an external_id. The external_id is required to populate your list through the SDK. To find out more, check out our guide.

           

          In order to subscribe a user to a Static List, create an ACCList object :

            You can also set a subscription expiration date. Once your subscription expires, the user will be removed from the Static List automatically.

              Add the user to a list or a set of lists :

                7.1.4 Subscription Tag

                A device tag has an identifier and a category associated with it. You can also add up to 5 parameters per tag.

                First, create the tag in a following way:

                  Add some parameters to the tag :

                    The tag can the be set (and later deleted if necessary) in a following way:

                      Device tag keys are unique therefore you need to use different ones when adding a set of values: 

                        You can set an expiration date for a device tag using a timestamp: 

                          Important

                          Please note that this feature is only available through Accengage's API

                          For more information please contact our Support Team at http://ticket.accengage.com

                          7.2 Behaviour tracking

                          7.2.1 Events tracking

                          Events are very useful to track user behaviors. One user may have multiple events, and all event occurrences are reported to the Accengage servers.

                          They can be used for : 

                          • In-app message or local push real-time triggering
                          • Application or campaign performance measuring
                          • Message targeting (subject to your app being integrated in the new platform).

                           

                          You will need to ask Accengage teams to activate events, and then you will be autonomous to create them in the Accengage dashboard (in settings > settings > add an event), so as to select them as triggers or targeting options.

                          Events are composed of a type (a numeric value which categorizes the type of event - see below), and parameters, which brings more information and can be targeted on (provided you are on the new platform).

                           

                          The library offers specific and useful methods to track standard events such as "add to cart" events, "purchases" or "leads". You can also track custom events for other user behaviors.

                          Important

                          The specified currency for cart and purchase tracking must be compliant with the current link ISO-4217 standard. If not, the tracking will be ignored.

                           

                          Add to cart

                          "Add to cart" events are useful to track and tag the fact that certain items were added to a basket. This is typically useful if you would like to set up "abandoned cart" campaigns, for which you will need to tag "add to cart" events, as well as "purchases".

                          The library provides a simple method to track items added to a cart. The type of all cart events is 30 but you don't need to specify it. For example, an iPhone 7 added to a new cart, can be tracked with:

                            If the user adds a new item to the same cart, you should use the same cart_id. For example, if he also adds an iPhone 7 Case to the same cart as the iPhone 7, track it with:


                              Purchases

                              "Purchase" events are very useful to tag your user's purchases within your app, to trigger or target messages based on them, but also to measure the revenues generated overall within your app, and thanks to your notification campaigns. Indeed, Accengage provides a statistic dashboard which measures this information (Statistics > advanced statistics).

                              The library provides a simple method to track purchases. The type of all purchase events is  50 , but you don't need to specify it. It is recommended to specify all the purchased items. For example, the purchase of the previous cart, can be tracked with :


                                Lead

                                "Lead" events are useful to track behaviours such as sign-up, registrations etc. The Accengage advanced statistic dashboard will also measure these leads.

                                The library also provides a simple method to track leads. You might want to track particular special event and action like an authentification. The type of a lead is  10 , but once again you don't need to specify it.

                                For example, a sign-up event, can be tracked with : 

                                  The total amount is optional when the purchased items are detailed. In this case, the server will calculate it for you. But, if the items set is nil or empty you must specify the total purchase amount.

                                  Important

                                  The purchase_id must be unique. Otherwise, the tracking will be ignored by the server.


                                  Custom events

                                  Apart from the special events seen above, you can tag and track any other event that will be useful for message triggering or targeting, thanks to custom events, such as "clicked on a certain button", "made a search, "invited a friend" etc.

                                  For all of these custom events, use thetrackEvent: method. 

                                  Events types below  1000  are reserved for the library internal usage. You can use custom event types starting from  1001, and you must specify them.

                                  Important

                                  Please note that the length of your concatenated parameters is restricted to 1024 characters : if you exceed this limitation, the SDK will truncate the value.

                                  Create a CustomEventParams object
                                    Add parameters to CustomEventParams object

                                    Four types of parameters are supported : NSString, NSNumber, BOOL and NSDate.

                                      Track the event

                                      Finally you can track the event you just created by using the Accengage's class trackEvent method :

                                        Note

                                        Each event needs to be defined in the Accengage User Interface. Go to Settings > Advanced Settings, and add a new event of type Custom with the code used in trackEvent method. The label is only used for a display purpose.

                                        7.2.2 Views

                                        In order to offer the best user experience, and let you trigger in-app messages at the most relevant time, on the right view (or avoid displaying them on certain views), the Accengage library allows you to track screens or views within your app.

                                        Unlike events, view tracking is not reported to our servers.

                                        Don't forget to configure your views in the Accengage dashboard (settings > settings > add a view) to display an understandable label for your product or marketing teams, and so that they can select them.

                                         

                                        Note

                                        We recommend exhaustively tracking every visible view in your app.

                                         

                                        The library offers an easy way to track a screen display and dismiss, you just need to import the Accengage.h and set the accengageAlias in the viewDidLoad: method:

                                          But if you prefer to track screens manually, you'll need to call the method trackScreenDisplay: in the viewDidAppear: method of your controller and the trackScreenDismiss: in viewDidDisappear:.

                                            7.2.3 States

                                            States allow you to trigger in-app messages or scheduled alarms. 

                                            To use this feature, you need to declare the states on Accengage dashboard (Settings > States) and then use them as a trigger.

                                            To set a state:

                                              To delete a state:

                                                7.3 Embedded web content tracking (in-app)

                                                If your application is hybrid and embeds webviews, you will probably want to tag certain information contained in your webviews.

                                                In that case, the regular methods of Update Device Information, or Events cannot be used, but tagging these information is possible if you follow the below instructions.

                                                Note

                                                In order to activate web content tracking, please contact your Accengage Project Manager for the exact procedure.

                                                First, follow one of those next steps depending on the component you're using: UIWebView or WKWebView.

                                                UIWebView

                                                If you're using the UIWebView component, just replace it with the A4SWebView.

                                                WKWebView

                                                If you're using the WKWebView component, you can simply replace it with the ACCWKWebView. But if you prefer avoiding the use of a subclass, you could implement the tracking manually.

                                                1. Inject the Accengage WKUserScript to your WKUserContentController 

                                                  • Add the handler for the Accengage messages 

                                                    • Initialize your WKWebView

                                                      • Handle the Accengage messages 

                                                          Once you've integrated the right component, you can now tag your web content.

                                                          To do so, follow this documentation.

                                                          Don't forget, as for regular custom user data or events, to declare them inside the Accengage dashboard.



                                                        7.4 Google Tag Manager bridge

                                                         

                                                        Setup the Accengage Bridge for GTM

                                                        1. Create (or use an existing) Firebase account.
                                                        2. Go to the Google Tag Management (GTM) console.
                                                        3. Create a GTM account - if you already have one, please go to step4
                                                          1. Indicate an account name.
                                                          2. Select a country.



                                                        4. Create your container:
                                                          1. Indicate its name.
                                                          2. Select your platform.
                                                          3. Choose the SDK version: Firebase.



                                                          Our bridge is compatible with Tag Manager + Firebase version only

                                                        5. Add the GTM dependency:

                                                          In your Podfile, add the following:

                                                        6. Add Accengage’s bridge:

                                                          Download the class ACCCustomTagProvider and add it to your project.
                                                        7. Go back to the GTM interface.
                                                        8. Submit your container changes and Publish the container or Create a version.



                                                        9. Download your container version.
                                                        10. Add the downloaded container to your project:
                                                          Copy the downloaded file into a folder called container in the XCode project root (usually PROJECT_ROOT/container/GTM-XXXXXX.json).
                                                        11. Preview your container.
                                                          To be able to test your GTM modification before publishing. Google Tag Manager enables you to preview versions of your container by generating links and QR codes in the Google Tag Manager web interface and using them to open your application.
                                                           

                                                          Preview container

                                                           

                                                          To preview a container, generate a preview URL in the Google Tag Manager web interface:

                                                           
                                                          1. Sign in to your Google Tag Manager account.
                                                          2. Select a mobile container.
                                                          3. Click Versions in the top navigation bar.
                                                          4. Click Actions > Preview on the container version you'd like to preview.
                                                          5. Enter your application's package name.
                                                          6. Click Generate begin preview link.


                                                            Save this preview URL for later steps.


                                                            To enable container previews, you must define the Google Tag Manager preview URL scheme in your project's property list. Under URL types of your application's property list file, register the following URL identifier and URL scheme:


                                                        Your Application is now well configured to trigger the Accengage SDK methods on Firebase events.

                                                        After that, you'll need to set up your tags on the GTM interface.

                                                        Follow the next steps to understand how to create Tags.

                                                        Accengage action key

                                                        The Accengage GTM bridge has to be used with a key acc_action to define what action you want Accengage to do with your parameters.

                                                        That key acc_action should be used with one of the following values :

                                                        • track_event
                                                        • track_lead
                                                        • track_add_to_cart
                                                        • track_purchase
                                                        • set_udi
                                                        • delete_udi
                                                        • increment_udi
                                                        • decrement_udi

                                                        Required parameters

                                                         As our tracking methods have some mandatory parameters, some methods will need some specific keys to work.


                                                        Create a Trigger

                                                        Want to know more about what is a GTM trigger? please follow this link

                                                        GTM Tags are fired on triggers. Then you'll need to create triggers to send Accengage SDK actions.
                                                        The conditions of your trigger depend on when you want the Accengage SDK action to be sent.
                                                        We recommend to use the Event Name that is already tagged in your application, but you can use whatever you want.

                                                         

                                                         

                                                        Create a Tag

                                                        Want to know more about what is a GTM tag? please follow this link

                                                          See the iOS documentation for more information about the TrackEvent.

                                                           

                                                          1. Create a new Tag
                                                          2. Add a previously created trigger: AccengageTrackEventTrigger in that case.
                                                          3. Set the tag type with Function Call
                                                          4. Indicate the classpath of the Accengage bridge in your application: ACCCustomTagProvider
                                                          5. Add the acc_action key and fill the value with the Accengage SDK action you want to do. In that case, track_event.
                                                          6. Then add the acc_event_id key with your event ID as a value.
                                                          7. You can also add some personal key/value. All of them will be added as parameters in the Accengage trackEvent method.



                                                          Note that all the event ID between 0 and 1000 are the default Accengage event. You custom event Id must be greater than 1000.

                                                          Also, Date should be sent as String on the following format: "yyyy-MM-dd HH:mm:ss zzz". For that, you can use our ACCCustomTagProvider method stringFromDate:

                                                          See the iOS documentation for more information about the TrackLead.

                                                           

                                                          1. Create a new Tag
                                                          2. Add a previously created trigger: AccengageTrackLeadTrigger in that case
                                                          3. Set the tag type with Function Call
                                                          4. Indicate the classpath of the Accengage bridge in your application: ACCCustomTagProvider
                                                          5. Add the acc_action key and fill the value with the Accengage SDK action you want to do. In that case, track_lead.
                                                          6. Then add the two mandatory keys of a Lead, acc_lead_label, and acc_lead_value.
                                                          7. Fill them with the appropriate values or variables.

                                                          See the iOS documentation for more information about the TrackAddToCart.

                                                           

                                                          1. Create a new Tag.
                                                          2. Add a previously created trigger : AccengageTrackAddToCartTrigger in that case
                                                          3. Set the tag type with Function Call
                                                          4. Indicate the classpath of the Accengage bridge in your application: ACCCustomTagProvider
                                                          5. Add the acc_action key and fill the value with the Accengage SDK action you want to do. In that case, track_add_to_cart.
                                                          6. Then add the mandatory keys for an Add To Cart, acc_cart_id, acc_item_id, acc_item_label, acc_item_category, acc_item_currency, acc_item_price and acc_item_quantity.
                                                          7. Fill them with the appropriate values or variables.

                                                          The value of acc_item_price should be of type double and the value of acc_item_quantity should be the type of int.

                                                          See the iOS documentation for more information about the TrackPurchase.

                                                           

                                                          1. Create a new Tag.
                                                          2. Add a previously created trigger: AccengageTrackPurchaseTrigger in that case
                                                          3. Set the tag type with Function Call
                                                          4. Indicate the classpath of the Accengage bridge in your application: ACCCustomTagProvider
                                                          5. Add the acc_action key and fill the value with the Accengage SDK action you want to do. In that case, track_purchase.
                                                          6. Then add the mandatory keys for a Purchase, acc_purchase_id, acc_purchase_currency, and acc_purchase_total_price.
                                                          7. Fill them with the appropriate values or variables.

                                                          The value of acc_purchase_total_price should be of type double.

                                                          There is another optional key that you can use acc_purchase_items, to send an array of items contained in the purchase using our ACCCustomTagProvider method  jsonFromCartItems:

                                                          See the iOS documentation for more information about the Update Device Information.

                                                           

                                                          There are two ways to use GTM to send an Accengage Update Device Information. Both of them have their own constraints and specificities. And both of them can be complementary.

                                                          Use Firebase Log Event

                                                          Like the other tracking methods, you can create a Tag to fire the Accengage updateDeviceInformation() method on a Firebase Log Event.

                                                          That requires you to call a Firebase Log Event, instead of Firebase setUserProperty() method in your code to send an Update Device Information to Accengage immediately.

                                                          For that, you'll have to :

                                                          1. Create a new Tag.
                                                          2. Add a previously created trigger: AccengageUDITrigger for example.
                                                          3. Set the tag type with Function Call.
                                                          4. Indicate the classpath of the Accengage bridge in your application: ACCCustomTagProvider.
                                                          5. Add the acc_action key and fill the value with the Accengage SDK action you want to do.
                                                            There are four possible actions for updating device information in Accengage :
                                                            • set_udi
                                                            • delete_udi
                                                            • increment_udi
                                                            • decrement_udi
                                                          6. Then add the keys you want to update in Accengage with the associated value.

                                                          The values should be of type double in case of increment_udi or decrement_udi action.

                                                          Also, Date should be sent as String on the following format: "yyyy-MM-dd HH:mm:ss zzz". For that, you can use our ACCCustomTagProvider method stringFromDate:

                                                          Use Firebase User Property

                                                          As expected, you may want to update Accengage device information on Firebase setUserProperty() method. At the moment, GTM triggers only fire when a Firebase Event occurs and all of the trigger conditions are true.

                                                          That means you can create another Trigger for your Update Device Information action and add a condition for the User Property in it. That trigger won't be immediately fired after the Firebase setUserProperty() method but after the next Firebase Event.

                                                          For that, you'll have to :

                                                          1. Create a new Tag.
                                                          2. Create a new Trigger: AccengageUDITrigger for example.
                                                            1. You can use a user property already tagged in your application as a trigger (or use a regex to match every value tagged in your application for a user property).
                                                          3. Set the tag type with Function Call.
                                                          4. Indicate the classpath of the Accengage bridge in your application: ACCCustomTagProvider.
                                                          5. Add the acc_action key and fill the value with the Accengage SDK action you want to do.
                                                            There are four possible actions for updating device information in Accengage :
                                                            • set_udi
                                                            • delete_udi
                                                            • increment_udi
                                                            • decrement_udi
                                                          6. Then add the keys you want to update in Accengage with the associated value.

                                                          The values should be of type double in case of increment_udi or decrement_udi action.

                                                          Also, Date should be sent as String on the following format: "yyyy-MM-dd HH:mm:ss zzz". For that, you can use our ACCCustomTagProvider method stringFromDate:


                                                          When you add key or value, you may want to use the value passed as parameters in the Firebase event method.

                                                          For that, you need to create a Variable in the GTM interface to retrieve your event parameters. Then you will have the possibility to use those variables in your Tags or others.

                                                          Want to know more about what is a variable? please follow this link.

                                                          Do not hesitate to have a look at the Google Tag Manager official documentation for iOS and Android to deeply understand the Accengage GTM bridge.

                                                           

                                                           

                                                          • No labels